amicus 4.3.0 → 4.4.1

package/src/utils/pricing.js

@@ -62,33 +62,136 @@ function lookupPricing(modelId) {
   return null;
 }
 
+/**
+ * Did we actually OBSERVE tokens THIS MODULE'S ESTIMATE CAN PRICE? (v4.4 B2,
+ * narrowed by v4.4.1 CA-7)
+ *
+ * This is the predicate that separates "the provider billed us for a $0 tier"
+ * from "we never saw a usage payload at all" — a distinction the old
+ * `pricing && tokens` guard could not make, because it only inspected the
+ * PRICE. It reads the normalized totals shape (input/output, as produced by
+ * sumPerMessageUsage) and OpenCode's raw per-message shape alike, because both
+ * carry `input`/`output` at the top level.
+ *
+ * ⚠️ CA-7: deliberately narrower than "did we see any token count at all". The
+ * estimate in resolveLegCost prices input/output ONLY, so accepting
+ * cacheRead/cacheWrite — and `reasoning`, which this predicate also used to
+ * accept and which the estimate likewise never prices — let a leg observed with
+ * none of input/output pass the observation gate and resolve to `estimated $0`:
+ * the same false-zero class the v4.4 observed-tokens fix exists to kill, in the
+ * one corner its predicate did not cover. Such a leg is now `unknown`, which is
+ * true, rather than free, which is not. Pricing cache or reasoning tokens
+ * properly needs catalog fields that may not exist; when they do, widen this and
+ * the estimate together, never one alone.
+ *
+ * Live-validated 2026-07-26: a real local leg reports `input: 25953, output: 3`,
+ * so the shipped v4.2 free-local `$0` promise (a local seat costs nothing but
+ * still reports real input/output) is untouched — tests/pricing-local.test.js
+ * is the standing guard on that.
+ * @param {object|null|undefined} tokens
+ * @returns {boolean}
+ */
+function hasObservedTokens(tokens) {
+  if (!tokens || typeof tokens !== 'object') { return false; }
+  return (tokens.input || 0) > 0 || (tokens.output || 0) > 0;
+}
+
 /** @returns {{amount:number|null, currency:'USD', source:'reported'|'estimated'|'unknown'}} */
 function resolveLegCost({ reportedCost, tokens, pricing }) {
   if (typeof reportedCost === 'number' && reportedCost > 0) {
     return { amount: reportedCost, currency: 'USD', source: 'reported' };
   }
-  if (pricing && tokens) {
+  // v4.4 B2: an all-zero token total is an ABSENCE OF OBSERVATION, not a $0
+  // bill. Pricing it as `0 × catalog = estimated $0` asserts "this seat was
+  // free" — a claim we cannot support, and one that silently under-counted the
+  // --max-cost ceiling on real paid runs (diagnosis §0: council-wsgate02 spent
+  // $0.9859 against a $0.75 ceiling while spent() believed $0.3720).
+  // The v4.2 §4.5 free-local-tier carve-out is DELIBERATELY preserved: a local
+  // Ollama/LM Studio seat legitimately costs $0 but still reports tokens, so
+  // hasObservedTokens() is true for it and it still resolves to `estimated $0`.
+  // v4.4.1 CA-7: a leg with no input/output falls through to `unknown` even when
+  // it reported cache or reasoning tokens — those are real observations, but not
+  // ones THIS estimate can turn into a price, so calling the result $0 would be
+  // the same fabrication one corner over. See hasObservedTokens above.
+  if (pricing && hasObservedTokens(tokens)) {
     const est = (tokens.input || 0) * pricing.prompt + (tokens.output || 0) * pricing.completion;
-    // v4.2 §4.5: a genuine $0 estimate is a REAL priced tier (not unknown/null).
     if (est >= 0) { return { amount: est, currency: 'USD', source: 'estimated' }; }
   }
   return { amount: null, currency: 'USD', source: 'unknown' };
 }
 
-/** Resolve a single run/leg's final usage block from raw totals + the model id. */
-function resolveUsage({ model, usageTotals }) {
+/**
+ * Resolve a single run/leg's final usage block from raw totals + the model id.
+ *
+ * @param {object} opts
+ * @param {string} opts.model full route id
+ * @param {object} opts.usageTotals sumPerMessageUsage output
+ * @param {boolean} [opts.subtreeUnknown] v4.4 Task 2 — this leg made a SUBAGENT
+ *   (`task`) tool call whose CHILD OpenCode session is billed separately, is NOT
+ *   rolled into the parent session's cost, and could NOT be enumerated (or could
+ *   only be walked in part). The leg's OWN cost may be perfectly `reported`; what
+ *   is unknown is its SUBTREE. Kept as a distinct concept from an unpriced leg
+ *   (which means "we observed no tokens at all") because they are different
+ *   statements and a reader must be able to tell them apart. Set only when true
+ *   so an ordinary leg's usage block stays byte-identical.
+ * @param {{sessions: number, tokens: object, costReported: number}} [opts.subtree]
+ *   v4.4.1 CA-1 — the child sessions that WERE enumerated and priced
+ *   (src/sidecar/child-sessions.js). Attached beside the leg's own cost rather
+ *   than folded into it: `cost` keeps meaning "this leg's own session", which is
+ *   what every existing reader already assumes, and the subtree is a separate
+ *   measurement that the wave rollup adds on top. Folding them together would
+ *   also let a measured child amount launder an UNKNOWN parent into a
+ *   `reported`-looking number — `council-wsgate02/wsgate02-s1-3` is exactly that
+ *   shape (own cost unknown, child session $0.471046).
+ */
+function resolveUsage({ model, usageTotals, subtreeUnknown, subtree }) {
   const totals = usageTotals || emptyUsageTotals();
   const cost = resolveLegCost({ reportedCost: totals.costReported, tokens: totals.tokens, pricing: lookupPricing(model) });
-  return { tokens: totals.tokens, cost };
+  const usage = { tokens: totals.tokens, cost };
+  if (subtree && subtree.sessions > 0) {
+    const amount = subtree.costReported;
+    usage.subtree = {
+      sessions: subtree.sessions,
+      tokens: subtree.tokens || emptyUsageTotals().tokens,
+      // A child session's price comes from OpenCode's own billing, never from a
+      // catalog estimate (the SDK's Session record carries no model id, so an
+      // estimate would be a guess). Children that exist but reported nothing are
+      // `unknown` — the B2 rule one level down, and never a $0 claim.
+      cost: amount > 0
+        ? { amount, currency: 'USD', source: 'reported' }
+        : { amount: null, currency: 'USD', source: 'unknown' },
+    };
+  }
+  if (subtreeUnknown) { usage.subtreeUnknown = true; }
+  return usage;
 }
 
-/** Aggregate leg usage into a wave-level usage block. Legs without usage count as unpriced. */
+/**
+ * Aggregate leg usage into a wave-level usage block. Legs without usage count as
+ * unpriced; legs carrying `subtreeUnknown` are counted separately in
+ * `subtreeUnknownLegs` — a fully-priced wave can still have an incomplete total.
+ *
+ * v4.4.1 CA-1: a leg's enumerated CHILD-session spend (`usage.subtree`) is added
+ * to the wave total here, and reported separately as `subtreeCost` /
+ * `subtreeSessions` so a reader can always see how much of the total came from
+ * subagents. It is added INDEPENDENTLY of whether the leg's own cost resolved —
+ * they are two different measurements, and dropping a measured child amount
+ * because its parent is unknown would be a second under-report on top of the
+ * one this whole change exists to close.
+ */
 function sumWaveUsage(legs) {
   const tokens = { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 };
   let amount = 0; let anyAmount = false;
-  let reportedLegs = 0, estimatedLegs = 0, unpricedLegs = 0;
+  let reportedLegs = 0, estimatedLegs = 0, unpricedLegs = 0, subtreeUnknownLegs = 0;
+  let subtreeCost = 0, subtreeSessions = 0;
   for (const leg of legs) {
     const u = leg && leg.usage;
+    if (u && u.subtreeUnknown) { subtreeUnknownLegs++; }
+    const st = u && u.subtree;
+    if (st && st.cost && typeof st.cost.amount === 'number') {
+      amount += st.cost.amount; anyAmount = true;
+      subtreeCost += st.cost.amount; subtreeSessions += st.sessions || 0;
+    }
     if (!u || !u.cost) { unpricedLegs++; continue; }
     for (const k of Object.keys(tokens)) { tokens[k] += (u.tokens && u.tokens[k]) || 0; }
     if (typeof u.cost.amount === 'number') { amount += u.cost.amount; anyAmount = true; }
@@ -101,7 +204,8 @@ function sumWaveUsage(legs) {
   else if (estimatedLegs > 0 && reportedLegs === 0 && unpricedLegs === 0) { source = 'estimated'; }
   else if (reportedLegs === 0 && estimatedLegs === 0) { source = 'unknown'; }
   else { source = 'mixed'; }
-  return { tokens, cost: { amount: anyAmount ? amount : null, currency: 'USD', source, reportedLegs, estimatedLegs, unpricedLegs } };
+  return { tokens, cost: { amount: anyAmount ? amount : null, currency: 'USD', source,
+    reportedLegs, estimatedLegs, unpricedLegs, subtreeUnknownLegs, subtreeCost, subtreeSessions } };
 }
 
 /**
@@ -119,4 +223,5 @@ function formatCost(cost) {
   return (cost.source === 'estimated' || cost.source === 'mixed') ? `~${dollars}` : dollars;
 }
 
-module.exports = { emptyUsageTotals, sumPerMessageUsage, lookupPricing, resolveLegCost, resolveUsage, sumWaveUsage, formatCost };
+module.exports = { emptyUsageTotals, sumPerMessageUsage, lookupPricing, hasObservedTokens,
+  resolveLegCost, resolveUsage, sumWaveUsage, formatCost };

package/src/utils/server-setup.js

@@ -75,10 +75,88 @@ function ensurePortAvailable(port = DEFAULT_PORT) {
   return false;
 }
 
+/**
+ * A start failure that is a LOCK RACE, not a deterministic error.
+ *
+ * OpenCode opens one shared SQLite database (~/.local/share/opencode/opencode.db)
+ * at startup, so two servers starting in the same instant can collide on it and
+ * the loser exits 1 with `database is locked`. Measured: council run v441plan01
+ * lost four of five seats in 736ms to exactly this.
+ *
+ * Deliberately NARROW. A missing binary, a bad key, a busy port and a config
+ * error are all deterministic — retrying them only triples the latency before
+ * the same failure, so they must fall straight through untouched.
+ */
+const LOCK_CLASS_START_FAILURE = /database is locked|database table is locked|SQLITE_BUSY/i;
+
+/**
+ * Backoff between start attempts; 5 attempts total, ≤3.75s of added latency.
+ *
+ * ⚠️ WIDENED from 3 attempts at 250/500ms (≤750ms) by v4.4.1 Step 10.5. 750ms is
+ * thin against a multi-megabyte WAL and any concurrent process touching the same
+ * OpenCode database: run v441plan02 exhausted it, the council degraded to one
+ * server per wave, and then lost four of five seats to the very race the retry
+ * exists to survive. The wait is bounded and paid at most once per acquisition;
+ * the cost of not waiting is a dead bench.
+ *
+ * Still lock-class ONLY — a deterministic failure (missing binary, bad key, busy
+ * port, config error) never sleeps a single millisecond here.
+ */
+const LOCK_RETRY_DELAYS_MS = [250, 500, 1000, 2000];
+
+/**
+ * @param {Error|null} error
+ * @returns {boolean} true only for a lock-class (retryable) start failure
+ */
+function isLockClassStartFailure(error) {
+  if (!error) { return false; }
+  // The real failure arrives as a message with the server's own stdout inlined
+  // ("Server exited with code 1 / Server output: … database is locked"), but
+  // check the usual carriers too so a wrapped/spawn-shaped error still matches.
+  const carriers = [error.message, error.stderr, error.stdout, error.cause && error.cause.message];
+  return carriers.some(c => typeof c === 'string' && LOCK_CLASS_START_FAILURE.test(c));
+}
+
+/**
+ * Run `attempt` with a BOUNDED retry on a lock-class failure only.
+ *
+ * Never fails closed: the final failure is rethrown unchanged, so every caller
+ * that already degrades on a start failure (runFanout writes an error wave; a
+ * council run falls back to per-wave servers) degrades exactly as before —
+ * just later, and far less often. This is the half of the fix that covers what
+ * a per-run shared server cannot: two separate `amicus` processes, or a CLI run
+ * beside a live MCP server, still contend for the same database.
+ *
+ * @param {(attempt: number) => Promise<T>} attempt
+ * @param {{retryDelayMs?: number}} [opts] retryDelayMs: test seam — collapses
+ *   every backoff to this value so a retry test does not sleep for real.
+ * @returns {Promise<T>}
+ * @template T
+ */
+async function retryOnLockRace(attempt, opts = {}) {
+  const delays = opts.retryDelayMs === undefined
+    ? LOCK_RETRY_DELAYS_MS
+    : LOCK_RETRY_DELAYS_MS.map(() => opts.retryDelayMs);
+  for (let i = 0; ; i += 1) {
+    try {
+      return await attempt(i);
+    } catch (error) {
+      if (i >= delays.length || !isLockClassStartFailure(error)) { throw error; }
+      logger.warn('OpenCode server start lost a lock race — retrying', {
+        attempt: i + 1, of: delays.length + 1, delayMs: delays[i], error: error.message,
+      });
+      await new Promise(resolve => setTimeout(resolve, delays[i]));
+    }
+  }
+}
+
 module.exports = {
   DEFAULT_PORT,
+  LOCK_RETRY_DELAYS_MS,
   isPortInUse,
   getPortPid,
   killPortProcess,
-  ensurePortAvailable
+  ensurePortAvailable,
+  isLockClassStartFailure,
+  retryOnLockRace
 };

package/src/utils/spend-ledger.js

@@ -45,7 +45,10 @@ const SPEND_LEDGER_FILE = 'spend-ledger.jsonl';
  * @param {string} [opts.waveId] present for a fanout leg
  * @param {string} opts.model resolved model id (or alias, if that's all the caller has)
  * @param {'headless'|'interactive'|'leg'} opts.mode
- * @param {{tokens:object, cost:{amount:number|null,currency:string,source:string}}|null} opts.usage
+ * @param {{tokens:object, cost:{amount:number|null,currency:string,source:string},
+ *   subtreeUnknown?:boolean}|null} opts.usage `subtreeUnknown` (v4.4.1 CA-2) is
+ *   copied onto the row when truthy — this leg's own cost resolved, but a child
+ *   session it spawned could not be priced, so the row's `cost` is a FLOOR
  * @param {string} [opts.op] 'leg' | 'start' | 'continue' | 'resume'
  * @param {string} [opts.status] terminal status
  * @param {string} [opts.councilRunId] council run id (additive attribution)
@@ -86,18 +89,36 @@ function appendSpend({ taskId, waveId, model, mode, usage,
     if (attempt !== undefined) { row.attempt = attempt; }
     if (substitutedFor !== undefined) { row.substitutedFor = substitutedFor; }
     if (retryOfWaveId !== undefined) { row.retryOfWaveId = retryOfWaveId; }
+    // v4.4.1 CA-2: a leg whose OWN cost is known but which spawned a child
+    // session the walk could not price writes a PRICED row — so `unpricedRows`
+    // never catches it and `amicus spend` reads as a complete measurement while
+    // `council run` says `costExact:false` about the same dollars. Omitted (not
+    // `|| false`) so a pre-4.4.1 row and an ordinary row stay identical, matching
+    // the linkage-field convention above.
+    if (usage.subtreeUnknown) { row.subtreeUnknown = true; }
     fs.appendFileSync(path.join(dir, SPEND_LEDGER_FILE), JSON.stringify(row) + '\n');
   } catch (e) {
     logger.debug('spend-ledger append failed (best-effort, run unaffected)', { taskId, error: e.message });
   }
 }
 
-/** @param {string} [dir] @returns {Array<object>} parsed rows; corrupt lines skipped */
+/**
+ * Read the ledger. Corrupt lines are skipped — and v4.4.1 A2 widens "corrupt"
+ * from "does not parse" to "does not parse AS A ROW". A line that is valid JSON
+ * but not a plain object (`"foo"`, `42`, `[1,2]`) used to survive `filter(Boolean)`
+ * and be treated as a row by every consumer: `aggregateSpend` counted it in
+ * `runs`, scored it into `unpricedRows`/`sourceMix.unknown` off its absent cost
+ * block, and `--rows` echoed it into a published document that says rows are
+ * objects. A scalar in a JSONL ledger of row objects is a corrupt line, so it is
+ * now dropped like any other — one fewer way the totals can be inflated by damage.
+ * @param {string} [dir] @returns {Array<object>} parsed rows; corrupt lines skipped
+ */
 function readSpendRows(dir) {
   const file = path.join(dir || getConfigDir(), SPEND_LEDGER_FILE);
   if (!fs.existsSync(file)) { return []; }
   return fs.readFileSync(file, 'utf-8').split('\n').map(l => l.trim()).filter(Boolean)
-    .map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+    .map(l => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(r => r !== null && typeof r === 'object' && !Array.isArray(r));
 }
 
 module.exports = { appendSpend, readSpendRows, SPEND_LEDGER_FILE, SPEND_LEDGER_SCHEMA_VERSION };

package/src/workspace/artifact-guard.js

@@ -0,0 +1,208 @@
+/**
+ * Council Workspace — artifact read guard (v4.4 §4.5 workspace:read-artifact).
+ *
+ * Two independent fences:
+ *  1. The name must be on the manifest-derived allowlist (fixed names +
+ *     review-/judge- files for run.json bench seats via v4.0's sanitizeName,
+ *     which strips every path separator) — traversal is unrepresentable.
+ *  2. The realpath of the resolved file must stay inside the realpath of the
+ *     run dir — a symlinked artifact cannot leak files from outside.
+ * >200 KB truncates with a flag (spec §4.5). report.html is deliberately NOT
+ * readable here — it opens externally via workspace:open-report.
+ */
+'use strict';
+
+const fsReal = require('fs');
+const path = require('path');
+const { sanitizeName } = require('../council/run-launch');
+const { readPointer } = require('./run-scan');
+const { isRealpathContained } = require('../utils/path-fence');
+
+const FIXED_ARTIFACTS = Object.freeze(['briefing-stage1.md', 'bundle-stage2.md', 'chair-packet.md', 'chair-output.md', 'tally-input.json']);
+// ⚠️ DE-ROT (F28): v4.1's debate stage writes five MORE run-dir artifact kinds the original
+// allowlist never named, so the Workspace hard-refused every `--debate` output with
+// `artifact not allowed: <name>`. Writers: tally-provisional.json = src/council/run.js:199;
+// revote-bundle.md = run-debate.js:119; debate.json = run-debate.js:261; the per-seat
+// rebuttal-/revote- pair = materializeDebate (run-launch.js:127-136).
+// ⚠️ FIVE KINDS, THREE ENTRIES — that is not a miscount (v4.4.1 DOC-7, re-verified). This const
+// holds only the three RUN-LEVEL names; the last two of the five, the rebuttal-/revote- pair, are
+// per BENCH MODEL and are appended inside artifactAllowlist below, next to review-/judge-.
+const DEBATE_ARTIFACTS = Object.freeze(['tally-provisional.json', 'revote-bundle.md', 'debate.json']);
+const MAX_ARTIFACT_BYTES = 200 * 1024;
+
+// isRealpathContained itself now lives in ../utils/path-fence.js (the shared "fence 2"
+// primitive: a realpath-based containment test that defeats symlink escapes AND
+// tampered/stale pointers). Re-exported below for backward compatibility — callers
+// outside this module (electron/ipc-workspace.js's workspace:open-report, this
+// file's own tests, and as of the third council-review pass src/workspace/run-detail.js
+// and src/workspace/run-scan.js) all reuse the exact same check rather than
+// re-implementing it. It could not stay defined here: run-scan.js needs it too, and
+// this file already requires run-scan.js for readPointer, so a shared leaf module
+// (no workspace/* deps of its own) is what keeps that from becoming a require cycle.
+
+/**
+ * Trim a buffer to at most `max` bytes without splitting a multi-byte UTF-8 character.
+ * A plain `buf.subarray(0, max)` can land mid-sequence — the tail bytes then decode as
+ * U+FFFD replacement characters, which can even push the encoded string back over `max`.
+ * Walks back over trailing continuation bytes (10xxxxxx) until it finds a clean boundary,
+ * dropping the whole partial character rather than emitting mojibake.
+ */
+function truncateUtf8(buf, max) {
+  let end = max;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) { end -= 1; }
+  return buf.subarray(0, end);
+}
+
+/**
+ * @param {object} run parsed run.json (may be partial)
+ * @returns {string[]} the allowlist. When two or more DISTINCT bench entries sanitize to the
+ *   same artifact name, a non-enumerable-in-spirit (but plain, test-visible) `collisions`
+ *   array is attached: `[{sanitized, models: [rawA, rawB, ...]}, ...]`. See the R4
+ *   council-review note below for why this is surfaced rather than silently deduped.
+ */
+function artifactAllowlist(run) {
+  const names = [...FIXED_ARTIFACTS];
+  const bench = run && Array.isArray(run.bench) ? run.bench : [];
+  // ⚠️ DE-ROT (F28): run.json carries a `debate` key ONLY on --debate runs, and it is seeded
+  // on the FIRST write (src/council/run.js:74-77), so this gate is safe and keeps the
+  // allowlist tight for the common case.
+  const debated = !!(run && run.debate);
+  if (debated) { names.push(...DEBATE_ARTIFACTS); }
+
+  // ⚠️ R4 COUNCIL REVIEW (fourth live paid council, major, unanimous): sanitizeName is NOT
+  // injective — it maps every character outside [a-zA-Z0-9._-] to '-', so two DISTINCT bench
+  // entries ('vendor/a', 'vendor?a') both produce 'vendor-a'. Both models would then request
+  // the SAME artifact file, and the renderer's `[data-artifact="..."]` lookup (drillIntoJudge)
+  // hands back whichever section matches first — prose silently misattributed to the wrong
+  // model. That is a run-integrity defect (this run directory genuinely cannot hold both
+  // models' review/judge files under distinct names), not a display quirk, so it must be
+  // DETECTED and surfaced, never smoothed away by deduping the resulting name list.
+  //
+  // A bench with genuinely REPEATED identical entries (['gemini', 'gemini']) is a different,
+  // harmless case that must keep collapsing to one set of rows (preserved intent) — collapse
+  // those via a Set over the RAW bench values FIRST, so identical entries never even reach
+  // the collision check below (only entries that are distinct as raw strings but coincide
+  // after sanitizeName count as a collision).
+  const uniqueModels = [...new Set(bench)];
+  const rawBySanitized = new Map(); // sanitized name -> first raw model seen for it
+  const collisionModels = new Map(); // sanitized name -> Set(raw models) once >1 raw maps to it
+  for (const m of uniqueModels) {
+    const s = sanitizeName(m);
+    if (rawBySanitized.has(s)) {
+      if (!collisionModels.has(s)) { collisionModels.set(s, new Set([rawBySanitized.get(s)])); }
+      collisionModels.get(s).add(m);
+    } else {
+      rawBySanitized.set(s, m);
+    }
+  }
+
+  for (const m of uniqueModels) {
+    names.push(`review-${sanitizeName(m)}.md`);
+    names.push(`judge-${sanitizeName(m)}.md`);
+    // rebuttal-/revote- are keyed on the same BENCH ALIAS through the same sanitizeName
+    // (materializeDebate is called with `d.raiser` / the revote leg's model — both aliases).
+    if (debated) {
+      names.push(`rebuttal-${sanitizeName(m)}.md`);
+      names.push(`revote-${sanitizeName(m)}.md`);
+    }
+  }
+  // `uniqueModels` already collapsed genuinely-repeated bench entries, so this final Set is
+  // now just a belt-and-suspenders no-op for names — it can no longer mask a real collision,
+  // since that path is detected above from the RAW (pre-sanitize) values instead.
+  const list = [...new Set(names)];
+  if (collisionModels.size) {
+    list.collisions = [...collisionModels.entries()].map(([sanitized, models]) => ({
+      sanitized, models: [...models],
+    }));
+  }
+  return list;
+}
+
+/**
+ * @param {string} project
+ * @param {string} runId
+ * @param {string} name artifact filename (must be allowlisted)
+ * @param {object} [deps] TEST-ONLY dependency injection: {realpathSync}. Never populate this
+ *   from renderer/caller-supplied input in production — an attacker-controlled realpathSync
+ *   would silently erase fence 2 (the realpath containment check below).
+ * @returns {{text: string, truncated?: true} | {error: string}}
+ */
+function readRunArtifact(project, runId, name, deps = {}) {
+  const realpathSync = deps.realpathSync || ((p) => fsReal.realpathSync(p));
+  const ptr = readPointer(project, runId);
+  if (ptr.error) { return { error: ptr.error }; }
+
+  let realDir;
+  try { realDir = realpathSync(ptr.runDir); }
+  catch { return { error: 'run dir unreadable' }; }
+
+  // ⚠️ COUNCIL REVIEW R2 (A1) / ROUND 4 ORDERING FIX (third live paid council, blocker):
+  // this outer fence — "runDir ITSELF (straight from the pointer file's JSON, validated
+  // only for truthiness by src/council/run-state.js's readPointer) stays inside project" —
+  // must run BEFORE any read reaches the filesystem. It used to run AFTER an unconditional
+  // read+JSON.parse of run.json from ptr.runDir: the fence still refused to hand back
+  // artifact bytes, so nothing ever leaked, but a tampered/stale pointer could still force
+  // this process to read-and-parse attacker-influenced JSON at an arbitrary path before any
+  // containment check ran — a parser surface with no corresponding gate. Mirrors
+  // src/workspace/run-detail.js's getRunDetail, which already resolves+fences BEFORE
+  // reading anything (round 3); this function was the one place in the workspace surface
+  // that got the ordering wrong. Also mirrors electron/ipc-workspace.js's
+  // workspace:open-report fence (first council review, finding C1): same isRealpathContained
+  // helper, same check, same error wording — now correctly ordered on the channel that
+  // actually serves artifact bytes (workspace:read-artifact and workspace:fold's
+  // chair-output.md read both funnel through this function).
+  let realProject;
+  try { realProject = realpathSync(project); }
+  catch { return { error: 'project unreadable' }; }
+  if (!isRealpathContained(realProject, realDir)) {
+    return { error: 'run directory escapes project' };
+  }
+
+  let run;
+  try { run = JSON.parse(fsReal.readFileSync(path.join(ptr.runDir, 'run.json'), 'utf-8')); }
+  // Generic message (round 4): a readFileSync failure's err.message embeds the full
+  // resolved path it tried to open — interpolating it here would hand the renderer an
+  // internal filesystem path (in the pre-fence-ordering bug, potentially one entirely
+  // outside the project) via the IPC response.
+  catch { return { error: 'run.json unreadable' }; }
+
+  if (!artifactAllowlist(run).includes(name)) { return { error: `artifact not allowed: ${name}` }; }
+
+  let realTarget;
+  try { realTarget = realpathSync(path.join(ptr.runDir, name)); }
+  catch (err) {
+    // ⚠️ v4.4.1 RN-10: this catch used to answer `not written yet: <name>` for ANY realpath
+    // failure — ENOENT, EACCES, EPERM, EIO, ELOOP, a dangling symlink — so a permission problem
+    // was indistinguishable from a file the council simply has not produced yet. That is not a
+    // cosmetic conflation: electron/ipc-workspace.js's workspace:fold reads chair-output.md
+    // through this function, and on a permission error it produced a silent CHAIRLESS fold that
+    // still reported {ok: true}. The logger.warn it now emits was the mitigation — but it logged
+    // this string, so the log said "not written yet" about a file that was right there.
+    //
+    // ⚠️ Keep the sanitization. Do NOT re-interpolate `err.message`: a realpath failure's message
+    // embeds the full resolved path it tried to open, which round 4 deliberately stopped handing
+    // back over IPC (see the run.json catch above). `err.code` is a bare symbolic errno with no
+    // path in it, and it is the one piece an operator reading the fold warning actually needs —
+    // whitelisted to the errno character class so nothing else can ever ride out through here.
+    const code = err && typeof err.code === 'string' && /^[A-Z][A-Z0-9_]{1,15}$/.test(err.code)
+      ? err.code : 'unknown';
+    if (code === 'ENOENT') { return { error: `not written yet: ${name}` }; }
+    return { error: `artifact unreadable (${code}): ${name}` };
+  }
+  if (!isRealpathContained(realDir, realTarget)) {
+    return { error: 'artifact escapes run directory' };
+  }
+
+  let buf;
+  try { buf = fsReal.readFileSync(realTarget); }
+  catch { return { error: 'artifact unreadable' }; }
+  if (buf.length > MAX_ARTIFACT_BYTES) {
+    return { text: truncateUtf8(buf, MAX_ARTIFACT_BYTES).toString('utf-8'), truncated: true };
+  }
+  return { text: buf.toString('utf-8') };
+}
+
+module.exports = {
+  artifactAllowlist, readRunArtifact, isRealpathContained,
+  FIXED_ARTIFACTS, DEBATE_ARTIFACTS, MAX_ARTIFACT_BYTES,
+};

package/src/workspace/blind-mode.js

@@ -0,0 +1,32 @@
+/**
+ * Council Workspace — blind-mode name mapping (v4.4 §6.3).
+ *
+ * Pure inversion helpers over run.json labelMap ({ 'Review A': model }).
+ * Finding ids are ALREADY label-space (A1, B2 — v4.0 anonymize), so blind
+ * mode never touches ids; it only swaps model display names for labels.
+ * Bias hygiene, not security (spec §6.1) — the map is user-readable on disk.
+ */
+'use strict';
+
+function buildNamePairs(labelMap) {
+  if (!labelMap || typeof labelMap !== 'object') { return []; }
+  const pairs = Object.entries(labelMap)
+    .filter(([label, model]) => typeof label === 'string' && typeof model === 'string')
+    .map(([label, model]) => ({ label, model }));
+  pairs.sort((a, b) => a.label.localeCompare(b.label));
+  return pairs;
+}
+
+function labelFor(model, labelMap) {
+  if (!labelMap || typeof labelMap !== 'object') { return null; }
+  for (const [label, m] of Object.entries(labelMap)) {
+    if (m === model) { return label; }
+  }
+  return null;
+}
+
+function pairFor(model, labelMap) {
+  return { model, label: labelFor(model, labelMap) };
+}
+
+module.exports = { buildNamePairs, labelFor, pairFor };