amicus 4.2.1 → 4.4.0

package/src/utils/pricing.js

@@ -62,33 +62,120 @@ function lookupPricing(modelId) {
   return null;
 }
 
+/**
+ * Did we actually OBSERVE any token usage for this leg? (v4.4 B2)
+ *
+ * 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. Accepts both the normalized totals shape (cacheRead/cacheWrite, as
+ * produced by sumPerMessageUsage) and OpenCode's raw per-message shape
+ * (`cache: {read, write}`), so callers holding either can ask one question.
+ * @param {object|null|undefined} tokens
+ * @returns {boolean}
+ */
+function hasObservedTokens(tokens) {
+  if (!tokens || typeof tokens !== 'object') { return false; }
+  const cache = tokens.cache && typeof tokens.cache === 'object' ? tokens.cache : {};
+  const cacheRead = tokens.cacheRead || cache.read || 0;
+  const cacheWrite = tokens.cacheWrite || cache.write || 0;
+  return (tokens.input || 0) > 0 || (tokens.output || 0) > 0
+    || (tokens.reasoning || 0) > 0 || cacheRead > 0 || cacheWrite > 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`.
+  // Only a leg where we observed no tokens at all falls through to `unknown`.
+  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 +188,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 +207,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/spend-ledger.js

@@ -46,9 +46,20 @@ const SPEND_LEDGER_FILE = 'spend-ledger.jsonl';
  * @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 {string} [opts.op] 'leg' | 'start' | 'continue' | 'resume'
+ * @param {string} [opts.status] terminal status
+ * @param {string} [opts.councilRunId] council run id (additive attribution)
+ * @param {string} [opts.councilName] council name (additive attribution)
+ * @param {string} [opts.project] project directory (additive attribution)
+ * @param {string} [opts.gateway] resolved gateway ('direct'|'openrouter'|'local', additive attribution)
+ * @param {number} [opts.attempt] fallback attempt count (omitted if absent)
+ * @param {string} [opts.substitutedFor] substituted model (omitted if absent)
+ * @param {string} [opts.retryOfWaveId] wave id being retried (omitted if absent)
  * @param {{dir?:string}} [ctx] test seam — dir overrides getConfigDir()
  */
-function appendSpend({ taskId, waveId, model, mode, usage }, ctx = {}) {
+function appendSpend({ taskId, waveId, model, mode, usage,
+  op, status, councilRunId, councilName, project, gateway,
+  attempt, substitutedFor, retryOfWaveId }, ctx = {}) {
   if (!usage) { return; }
   try {
     const dir = ctx.dir || getConfigDir();
@@ -62,7 +73,19 @@ function appendSpend({ taskId, waveId, model, mode, usage }, ctx = {}) {
       mode: mode || null,
       tokens: usage.tokens || null,
       cost: usage.cost || null,
+      // v4.3 additive attribution (spec 7.1). Nullable dimensions default to
+      // null (so a row is always groupable); linkage fields are OMITTED unless
+      // present (they only exist on fallback/retry rows).
+      op: op || null,
+      status: status || null,
+      councilRunId: councilRunId || null,
+      councilName: councilName || null,
+      project: project || null,
+      gateway: gateway || null,
     };
+    if (attempt !== undefined) { row.attempt = attempt; }
+    if (substitutedFor !== undefined) { row.substitutedFor = substitutedFor; }
+    if (retryOfWaveId !== undefined) { row.retryOfWaveId = retryOfWaveId; }
     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 });

package/src/workspace/artifact-guard.js

@@ -0,0 +1,187 @@
+/**
+ * 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).
+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 { return { error: `not written yet: ${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 };

package/src/workspace/fold-format.js

@@ -0,0 +1,95 @@
+/**
+ * Council Workspace — fold payload builder (v4.4 §7).
+ *
+ * MIRRORS the shipped fold-header builder `formatFoldOutput`
+ * (src/headless.js:775-789, exported at :797, re-exported from src/index.js:20)
+ * — byte-for-byte the same 8-line head. src/headless.js is the SOURCE OF
+ * TRUTH; keep the head in sync with it. The duplication is deliberate:
+ * requiring headless.js transitively pulls opencode-client / progress /
+ * conversation-mirror at require time (src/headless.js:8-17), which
+ * src/workspace/ must stay free of.
+ * ⚠️ DE-ROT (F58): the header used to claim it "reuses the v4.0 marker/nonce
+ * contract exactly" while silently dropping formatFoldOutput's nonce-required
+ * throw (src/headless.js:776-778). The guard is restored in buildFoldText below.
+ * No model call — the chair result already exists on disk, so a workspace fold
+ * is a local read+format.
+ * The chair body is UNTRUSTED model text: it passes through stripFoldMarkers
+ * before embedding, so chair prose containing a marker can never truncate or
+ * spoof the fold (the exact hazard the nonce closure exists for).
+ * Degradation mirrors the engine's ladder: no chair → VERDICT: none + tally
+ * summary; pre-tally → stage/status summary. Never blocked, always labeled.
+ */
+'use strict';
+
+const { buildFoldMarker, stripFoldMarkers } = require('../utils/fold-marker');
+const { formatCost } = require('../utils/pricing');
+
+function ok(doc) { return doc && !doc.parseError ? doc : null; }
+
+function tierLine(tierCounts) {
+  const t = tierCounts || {};
+  const n = (k) => (typeof t[k] === 'number' ? t[k] : 0);
+  return `Tiers: Confirmed ${n('Confirmed')} · Disputed ${n('Disputed')} · Contested ${n('Contested')} · Singleton ${n('Singleton')}`;
+}
+
+function stageSummary(run) {
+  const stages = Array.isArray(run.stages) ? run.stages : [];
+  return stages.length ? stages.map((s) => `${s.name}: ${s.status}`).join(' · ') : 'no stages recorded';
+}
+
+/**
+ * @param {object} o {nonce, project, run, tally?, verdict?, chairText?}
+ * @returns {string} the fold block (marker first line; no trailing newline)
+ */
+function buildFoldText(o) {
+  // ⚠️ DE-ROT (F58): mirror formatFoldOutput's v4.0 §9 guard (src/headless.js:776).
+  // Without it a missing nonce emits `[SIDECAR_FOLD:]`, which the hex-only marker
+  // regex (src/utils/fold-marker.js:68) never parses — a silently unfoldable block.
+  if (!o || !o.nonce) { throw new TypeError('buildFoldText requires a per-run nonce (v4.0 §9)'); }
+  const run = o.run || {};
+  const verdict = ok(o.verdict);
+  const tally = ok(o.tally);
+  // Review follow-up #2: verdict.json is NOT re-validated here (the
+  // amicus_verdict MCP path types overallVerdict as a bare z.string().nullable()
+  // — mcp-tools.js:428), so a multi-line or marker-bearing value must never
+  // reach the head verbatim: an embedded '\n' would shift every line below
+  // VERDICT: (a raw string containing '\n' becomes several elements once the
+  // head array is '\n'-joined), and an embedded marker could spoof the fold.
+  // Safe on the shipped engine path (parseChairVerdict returns a canonical
+  // CHAIR_VERDICTS phrase) — this is defense-in-depth, not a fix for a real
+  // producer.
+  const overall = verdict && verdict.overallVerdict
+    ? stripFoldMarkers(String(verdict.overallVerdict)).replace(/[\r\n]+/g, ' ').trim()
+    : null;
+  const tierCounts = (verdict && verdict.tierCounts) || (tally && tally.tierCounts) || null;
+  const cost = run.usage && run.usage.cost ? run.usage.cost : null;
+
+  const head = [
+    buildFoldMarker(o.nonce),
+    `Model: ${run.chair || 'unknown'}`,
+    `Session: ${run.runId || 'unknown'}`,
+    'Client: council-workspace',
+    `CWD: ${o.project}`,
+    'Mode: council',
+    '---',
+    `VERDICT: ${overall || 'none'}`,
+  ];
+  if (tierCounts) {
+    head.push(tierLine(tierCounts));
+  } else {
+    head.push(`Run: ${run.status || 'unknown'} — ${stageSummary(run)}`);
+  }
+  head.push(`Cost: ${formatCost(cost)}${cost && cost.source ? ` (${cost.source})` : ''}`);
+
+  // Review follow-up #1: strip FIRST, then test emptiness on the STRIPPED
+  // result — not the raw one. A chair body consisting solely of a marker
+  // line (plus whitespace) is non-empty raw but strips to '', and must fall
+  // back to the tally-summary label rather than embedding a blank body.
+  const stripped = o.chairText ? stripFoldMarkers(String(o.chairText)).trim() : '';
+  const body = stripped
+    || (tierCounts ? '(no chair output — tally summary above)' : '(pre-tally: stage summary above)');
+
+  return `${head.join('\n')}\n${body}`;
+}
+
+module.exports = { buildFoldText };

package/src/workspace/live-normalize.js

@@ -0,0 +1,156 @@
+/**
+ * Council Workspace — live-doc normalization (v4.4 §3 A1/A2/A4 seam).
+ *
+ * ONE defensive mapping from the v4.3 composed live doc (the amicus_status
+ * rollup stamped view:'live') to the renderer's seat model. If the merged
+ * composed-doc shape ever drifts, THIS file moves and nothing else does.
+ * Liveness/staleness is passed through, never invented here (A4).
+ *
+ * The council composed doc (buildCouncilStatusPayload, src/mcp-council-
+ * awareness.js) is UNVERSIONED (F63) and carries: {taskId, type, runId,
+ * runDir, status, currentStage, stages:[{name,status,waveId}], legsTotal,
+ * legsComplete, elapsed, exitCode, version, view:'live', usage?, reason?,
+ * legs:[{taskId, model, modelInput, role, status, messages, stage,
+ * latestPreview, lastActivityAt, stalled, usage?}], stalled?,
+ * stalledForSeconds?}. Do NOT copy the WAVE doc's shape (src/mcp-server.js:
+ * 592-662) — that is a different document, gated on metadata.type === 'wave'.
+ */
+'use strict';
+
+const { formatCost } = require('../utils/pricing');
+const { TERMINAL_STATUSES } = require('./run-detail');
+
+function legRowsOf(doc) {
+  if (Array.isArray(doc.legs)) { return doc.legs; }
+  if (doc.wave && Array.isArray(doc.wave.legs)) { return doc.wave.legs; }
+  return [];
+}
+
+function numOrNull(v) { return typeof v === 'number' ? v : null; }
+
+function seatOf(leg) {
+  const usage = leg.usage || null;
+  const tokens = usage && usage.tokens ? usage.tokens : null;
+  return {
+    id: leg.taskId || leg.legId || null,
+    // ⚠️ DE-ROT (F34/F36): `model` and `modelInput` are TWO SEPARATE fields, never collapsed.
+    // A live leg's `model` is the resolved executable id (e.g. `google/gemini-2.5`); `modelInput`
+    // is the council ALIAS (e.g. `gemini`) that run.json's labelMap and blind mode's labelFor()
+    // key on (src/council/anonymize.js:30 stamps labelMap values from the alias, never the
+    // resolved id). The already-shipped electron/workspace-ui/live-model.js:55 reads
+    // `seat.modelInput || seat.model` to pick the alias for its label lookup — collapsing the two
+    // into one field here would silently break blind mode (a resolved-id lookup never matches
+    // labelMap, leaking the real model id instead of degrading to a label or an em-dash).
+    model: leg.model || null,
+    modelInput: leg.modelInput || null,
+    role: leg.role || null,
+    status: leg.status || 'unknown',
+    // ⚠️ PRE-FLIGHT (P5): `leg.phase` is dead weight — Task 0.5 does not emit it. `leg.stage` IS
+    // emitted (src/observe/council-legs.js:88), so it is the only source; no fallback to invent.
+    stage: leg.stage || null,
+    messages: leg.messages === undefined ? null : leg.messages,
+    tokensIn: tokens ? numOrNull(tokens.input) : null,
+    tokensOut: tokens ? numOrNull(tokens.output) : null,
+    costDisplay: usage && usage.cost ? formatCost(usage.cost) : null,
+    // ⚠️ PRE-FLIGHT (P5): maps the ISO `lastActivityAt` only. `leg.lastActivity` /
+    // `leg.latestActivity` do not exist on a real leg row (`latestActivity` is an action LABEL —
+    // "Using <tool>" — not a time), so falling back to either would put prose in a timestamp
+    // column or leave it permanently null.
+    lastActivity: leg.lastActivityAt || null,
+    latestPreview: leg.latestPreview || null,
+    stalled: leg.stalled === true,
+  };
+}
+
+/**
+ * How many legs in this stage rollup contributed NO amount (v4.4 §8). Read off
+ * sumWaveUsage's `unpricedLegs` (src/observe/live-doc.js rollupWaveUsage), which
+ * the composed doc already carries — nothing new is invented renderer-side.
+ */
+function liveUnknownLegs(doc) {
+  const c = doc.usage && doc.usage.cost ? doc.usage.cost : null;
+  return (c && typeof c.unpricedLegs === 'number') ? c.unpricedLegs : 0;
+}
+
+/**
+ * How many legs in this rollup have an unattributed subagent SUBTREE (v4.4
+ * Task 2) — their own cost is known, but they spawned a child OpenCode session
+ * that is billed separately and never enumerated. Distinct from an unpriced leg,
+ * and the reason a fully-priced total can still be short.
+ */
+function liveSubtreeUnknownLegs(doc) {
+  const c = doc.usage && doc.usage.cost ? doc.usage.cost : null;
+  return (c && typeof c.subtreeUnknownLegs === 'number') ? c.subtreeUnknownLegs : 0;
+}
+
+function liveCostDisplay(doc) {
+  if (!doc.usage || !doc.usage.cost) { return null; }
+  const base = formatCost(doc.usage.cost);
+  const parts = [];
+  const unknown = liveUnknownLegs(doc);
+  const subtree = liveSubtreeUnknownLegs(doc);
+  if (unknown > 0) { parts.push(`${unknown} unknown`); }
+  if (subtree > 0) { parts.push(`${subtree} subagent subtree`); }
+  return parts.length > 0 ? `${base} + ${parts.join(' + ')}` : base;
+}
+
+/**
+ * @param {object} doc composed live doc (amicus_status payload)
+ * @returns {object} LiveModel (see plan Shared contracts); {ok:false, error?} on junk
+ */
+function normalizeLive(doc) {
+  if (!doc || typeof doc !== 'object') { return { ok: false, error: 'no live doc' }; }
+  const stages = Array.isArray(doc.stages) ? doc.stages : null;
+  const active = stages ? (stages.find((s) => s.status === 'running') || null) : null;
+  const status = doc.status || 'unknown';
+  return {
+    ok: true,
+    view: doc.view || null,
+    runId: doc.runId || doc.taskId || null,
+    status,
+    // ⚠️ PRE-FLIGHT (P6): the fallback read `doc.stage`, which NO producer emits — the council
+    // payload's field is `currentStage` (src/mcp-council-awareness.js:155). Harmless today only by
+    // coincidence: `currentStage` is computed from the same `stages.find(status === 'running')`
+    // predicate as `active`, so both arms are null in exactly the same cases. But it is the same
+    // read-a-field-nobody-writes class as P5, and this is the arm that would matter if `stages`
+    // ever arrived non-array. Read the field that exists.
+    stageName: active ? active.name : (doc.currentStage || null),
+    stages,
+    seats: legRowsOf(doc).map(seatOf),
+    // The two counters the payload already ships (src/mcp-council-awareness.js:149) — the honest
+    // fallback readout if a seat row is ever unavailable.
+    legsTotal: typeof doc.legsTotal === 'number' ? doc.legsTotal : null,
+    legsComplete: typeof doc.legsComplete === 'number' ? doc.legsComplete : null,
+    // ⚠️ DE-ROT (F39): these two are ACTIVE-STAGE spend, not the run total.
+    // buildCouncilStatusPayload rolls up only the legs of the currently-RUNNING stage's sub-waves
+    // (mcp-council-awareness.js:136-146) and omits `usage` entirely until one of those legs flushes
+    // progress.usage (:154), so the number under-reports and RESETS at each stage boundary; stages
+    // with no `project` (tally, verdict) contribute nothing. Decision: keep the field, LABEL it
+    // stage-scoped in the renderer (Task 15 suffixes the gauge text "(this stage)"). Do NOT try to
+    // add it onto `derived.cost.costAmount` — that is null for the entire life of the live loop
+    // (run-detail reads run.json's `usage`, which stays null until finalize(), run.js:98-102), so
+    // "adding" is just a rename of the same stage figure. The only run total is the terminal one.
+    // v4.4 §8: same treatment as the terminal panel (run-detail.js costPanel) —
+    // a stage rollup that omits unpriced legs reads as the full stage spend.
+    costDisplay: liveCostDisplay(doc),
+    costAmount: doc.usage && doc.usage.cost && typeof doc.usage.cost.amount === 'number' ? doc.usage.cost.amount : null,
+    costUnknownLegs: liveUnknownLegs(doc),
+    costSubtreeUnknownLegs: liveSubtreeUnknownLegs(doc),
+    costExact: liveUnknownLegs(doc) === 0 && liveSubtreeUnknownLegs(doc) === 0,
+    flags: {
+      // ⚠️ DE-ROT (F03): `crashed` exists nowhere on the composed doc — Task 0.5 deliberately did
+      // not add one (out of scope; see task-0.5-report.md). A crashed council instead flips
+      // `status` to 'error' and stamps `reason` from run.error
+      // (src/mcp-council-awareness.js:110-123) — that is the only real signal, so `crashed` is
+      // DERIVED from it here rather than read off a `doc.crashed` field that no real payload ever
+      // sets. This is still "never invented renderer-side" (A4): the derivation lives in this
+      // seam, not in electron/workspace-ui/*, and uses only fields the data layer actually wrote.
+      crashed: status === 'error' && Boolean(doc.reason),
+      stalled: doc.stalled === true,
+      stalledForSeconds: typeof doc.stalledForSeconds === 'number' ? doc.stalledForSeconds : null,
+    },
+    terminal: TERMINAL_STATUSES.includes(status),
+  };
+}
+
+module.exports = { normalizeLive };