amicus 4.3.0 → 4.4.1

package/src/workspace/fold-format.js

@@ -0,0 +1,124 @@
+/**
+ * Council Workspace — fold payload builder (v4.4 §7).
+ *
+ * MIRRORS the shipped fold-header builder `formatFoldOutput`
+ * (src/headless.js `formatFoldOutput`, exported from src/headless.js and
+ * re-exported from src/index.js) — byte-for-byte the same **7-line** head:
+ * marker, Model, Session, Client, CWD, Mode, `---`. ⚠️ v4.4.1 DOC-5: this said
+ * "8-line" for two releases. Line 8 (`VERDICT:`) is council's OWN addition and
+ * has no counterpart in formatFoldOutput, whose 8th element is the summary
+ * body. Only the first 7 lines are the shared contract; anyone changing the
+ * shared format must sync those and leave `VERDICT:` alone.
+ * src/headless.js is the SOURCE OF TRUTH; keep the head in sync with it.
+ * (Line numbers deliberately omitted — the previous `:775-789`/`:797` citation
+ * had drifted by ~500 lines.) 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)}`);
+  }
+  // ⚠️ v4.4.1 DOC-5: this used to append ` (${cost.source})` for EVERY source,
+  // on top of a glyph formatCost had already spent on the same fact —
+  // `~$0.0100 (estimated)`, `? (unknown)`. formatCost (src/utils/pricing.js)
+  // prefixes `~` for both 'estimated' and 'mixed', and returns a bare `?` when
+  // the source is 'unknown'. So for 'estimated' and 'unknown' the word was pure
+  // repetition and is gone.
+  //
+  // Two sources still spell themselves out, because the glyph vocabulary cannot
+  // express them:
+  //   - `reported` — a plain `$0.4321` is also what an unrecognised/absent
+  //     source renders as, so the absence of a glyph cannot mean "exact".
+  //   - `mixed` — `~` encodes *inexact*, not *which kind of inexact*. Collapsing
+  //     'mixed' into a bare `~$…` makes it indistinguishable from 'estimated',
+  //     and the two are not the same claim: 'mixed' means some legs reported
+  //     real usage and some were estimated, i.e. part of this number is
+  //     measured. That is strictly more information than 'estimated', and this
+  //     is the fold line of a release whose theme is cost truthfulness.
+  // Each thing is still said exactly once — the `~` says "inexact", the word
+  // says "which kind", and neither restates the other.
+  const costSourceLabel = cost && (cost.source === 'reported' || cost.source === 'mixed')
+    ? ` (${cost.source})`
+    : '';
+  head.push(`Cost: ${formatCost(cost)}${costSourceLabel}`);
+
+  // 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,169 @@
+/**
+ * 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');
+
+// ⚠️ v4.4.1 RN-7: the `doc.wave.legs` fallback that used to sit here is GONE, deliberately.
+// No producer nests legs under `wave` — the WAVE composed doc (src/mcp-server.js:592-662)
+// carries a TOP-LEVEL `legs`, exactly like the council one, and this file's header already
+// says not to model the wave doc at all. The arm asserted a shape that does not exist, and
+// wsgate01's reviewer believed it. If a nested shape ever appears, add it back WITH a
+// producer to point at.
+function legRowsOf(doc) {
+  return Array.isArray(doc.legs) ? doc.legs : [];
+}
+
+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 {
+    // ⚠️ v4.4.1 RN-7: `leg.legId` was a second dead fallback here — no leg row, council or
+    // wave, has ever carried it (src/observe/council-legs.js stamps `taskId`). Deleted.
+    id: leg.taskId || 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,
+    // ⚠️ v4.4.1 RN-7 (was PRE-FLIGHT P6): the `|| doc.currentStage` fallback is GONE. P6 had
+    // already corrected it once — from the phantom `doc.stage` to the real `currentStage` — and
+    // its own comment conceded the arm was "harmless today only by coincidence". It is in fact
+    // strictly unreachable: buildCouncilStatusPayload writes `stages` as `(run.stages || []).map(…)`
+    // (always an array) and derives `currentStage` from the SAME
+    // `stages.find(s => s.status === 'running')` predicate `active` uses one line up
+    // (src/mcp-council-awareness.js:155-157), so `active` is null in exactly the cases
+    // `currentStage` is too. Keeping it asserted a divergence between the two fields that no
+    // producer can create.
+    stageName: active ? active.name : null,
+    stages,
+    seats: legRowsOf(doc).map(seatOf),
+    // ⚠️ v4.4.1 RN-8 (D1 ruling: delete the promise). `legsTotal`/`legsComplete` used to be
+    // mapped here under a comment promising them as "the honest fallback readout if a seat row
+    // is ever unavailable" — a UI fallback nobody ever wired. Nothing in electron/workspace-ui/
+    // read either field. Documenting a feature that does not exist is worse than not having it,
+    // so the fields and the promise are both gone. ⚠️ The SAME names on the composed doc
+    // (src/mcp-council-awareness.js) and in src/cli-handlers-status.js / src/mcp-wait.js ARE
+    // consumed — this deletion is scoped to the workspace's LiveModel only. If a future task
+    // wants the counters in the GUI, re-add them WITH the renderer that paints them.
+    // ⚠️ 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 };

package/src/workspace/matrix-model.js

@@ -0,0 +1,94 @@
+/**
+ * Council Workspace — adjudication matrix view model (v4.4 §5.2).
+ *
+ * Pure: tally.json + labelMap (+ verdict.json) → renderable rows/cells.
+ * Symbols come from council/report.js SYMBOL (single source — the report and
+ * the workspace can never disagree about what the symbols mean). Every
+ * name-bearing field carries BOTH spellings ({model, label}) so the
+ * renderer's blind toggle is a pure display flip with no re-fetch. Missing
+ * votes (partial waves) are blank cells, never invented neutrals — tier math
+ * already excluded them (v4.0).
+ *
+ * ⚠️ DE-ROT (F07): `tally()` writes `tierOverride: null` on EVERY finding,
+ * unconditionally (src/council/tally.js:106) — it is never a real source for
+ * either the override badge or the post-override tier. Only `buildVerdict`
+ * materializes `{from,to,reason}` and rewrites `tier` to `tierOverride.to`
+ * (src/council/verdict.js:33-37). So both fields are joined in from
+ * verdict.findings[] by `id`; when verdict is absent/unparseable (caller
+ * passes null/undefined, or a finding has no verdict-side counterpart) the
+ * row falls back to tally's own (pre-override) tier and renders no badge.
+ */
+'use strict';
+
+const { SYMBOL } = require('../council/report');
+const { pairFor } = require('./blind-mode');
+
+/** Index verdict.findings[] by id, tolerating an absent/malformed verdict doc. */
+function indexVerdictFindings(verdict) {
+  const byId = new Map();
+  if (verdict && Array.isArray(verdict.findings)) {
+    for (const vf of verdict.findings) {
+      if (vf && typeof vf.id === 'string') { byId.set(vf.id, vf); }
+    }
+  }
+  return byId;
+}
+
+/**
+ * @param {object} tally parsed tally.json
+ * @param {object} labelMap run.json labelMap
+ * @param {object|null} [verdict] parsed verdict.json — source of truth for
+ *   tierOverride and the post-override tier (⚠️ DE-ROT F07). Omitted, null,
+ *   or a finding missing from it falls back to tally's tier with no badge.
+ * @returns {object} MatrixModel (see plan Shared contracts)
+ */
+function buildMatrixModel(tally, labelMap, verdict) {
+  const map = labelMap || {};
+  const judges = tally && tally.meta && Array.isArray(tally.meta.models) ? tally.meta.models : [];
+  const findings = tally && Array.isArray(tally.findings) ? tally.findings : [];
+  const verdictById = indexVerdictFindings(verdict);
+
+  const rows = findings.map((f) => {
+    const votes = {};
+    for (const adj of (Array.isArray(f.adjudications) ? f.adjudications : [])) {
+      if (!adj || typeof adj.judge !== 'string') { continue; }
+      votes[adj.judge] = adj.verdict;
+    }
+    const vf = verdictById.get(f.id);
+    return {
+      id: f.id,
+      severity: f.severity || null,
+      tier: (vf ? vf.tier : null) || f.tier || null,
+      thin: f.confidence === 'thin',
+      tierOverride: (vf && vf.tierOverride) || null,
+      // ⚠️ DE-ROT (F29): v4.1 decorates tally.json findings in place with
+      // `debate: {action, previousTier}` (src/council/debate.js:71-75; action ∈
+      // defended|amended|withdrawn|no-response) and verdict.json carries it through
+      // (src/council/verdict.js:43). Consumed by electron/workspace-ui/workspace-matrix.js's
+      // renderMatrix, which renders a `.debate-badge` in the tier cell (alongside the
+      // thin/tierOverride badges) so a withdrawn/amended/defended/no-response finding never
+      // renders as an ordinary live row. Absent on non-debate runs, hence `|| null`.
+      debate: f.debate || null,
+      raiser: pairFor(f.raiser, map),
+      basis: f.basis || { a: 0, d: 0, n: 0 },
+      cells: judges.map((j) => {
+        const vote = Object.prototype.hasOwnProperty.call(votes, j) ? votes[j] : null;
+        return {
+          judge: pairFor(j, map),
+          verdict: vote,
+          sym: vote ? (SYMBOL[vote] || '?') : ' ',
+          isRaiser: j === f.raiser,
+        };
+      }),
+    };
+  });
+
+  return {
+    judges: judges.map((j) => pairFor(j, map)),
+    rows,
+    tierCounts: (tally && tally.tierCounts) || null,
+    judged: !(tally && tally.judged === false),
+  };
+}
+
+module.exports = { buildMatrixModel };

package/src/workspace/run-detail.js

@@ -0,0 +1,229 @@
+/**
+ * Council Workspace — run detail: defensive parse of run.json / tally.json /
+ * verdict.json + the derived view models the renderer paints (v4.4 §4.5
+ * workspace:get-run, §5.2, §9). Malformed JSON yields {parseError, rawPath}
+ * per document — one bad file never blanks the whole run (spec §9 row 1).
+ * Read-only (§6.2).
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { formatCost } = require('../utils/pricing');
+const { readPointer } = require('./run-scan');
+const { buildNamePairs } = require('./blind-mode');
+const { buildMatrixModel } = require('./matrix-model');
+const { artifactAllowlist } = require('./artifact-guard');
+const { isRealpathContained } = require('../utils/path-fence');
+
+/**
+ * Shared terminal-status list (also mirrored renderer-side in live-model.js).
+ * ⚠️ DE-ROT (F26): deliberate HAND-COPY of src/observe/live-doc.js:18 `TERMINAL`,
+ * names and order byte-identical. Do NOT require() it — Task 3 is Phase 1
+ * ("zero v4.3") and live-doc.js is v4.3. Not to be confused with the shipped
+ * src/utils/result-schema.js:13 TERMINAL_STATUSES, which is the LEG set (no 'partial').
+ */
+// ⚠️ v4.4.1 A1: 'timed-out' added alongside 'timeout' — see the long note at
+// src/observe/live-doc.js:18 for why both spellings are real and which producer writes each.
+// Council run.json only ever carries aborted|complete|error|partial (run-finalize.js:38
+// statusForExit), so the new name is inert for THIS module's own reads; it is carried anyway
+// because the drift pin demands byte-identity with the source list, and that pin is the only
+// thing keeping the three copies honest.
+const TERMINAL_STATUSES = ['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'timed-out', 'idle-timeout'];
+
+/** Friendly labels for known v4.0 stage names; unknown names pass through raw
+ *  — the graceful-when-present rule (spec §5.2). */
+// ⚠️ PRE-FLIGHT (P1): this table was a DIFFERENT 7-key table whose keys and values both
+// disagreed with Task 12's renderer mirror — while Task 12 Step 1 pins them with
+// `expect(STAGE_LABELS).toEqual(rd.STAGE_LABELS)` (deep equality, guaranteed red). It also
+// carried `repairs` and `debate`, two names DE-ROT F10 proved the engine NEVER writes.
+// Task 12's table is now the single source and is reproduced here byte-for-byte. If you edit
+// one, edit both — the drift pin is the only thing keeping them honest.
+const STAGE_LABELS = {
+  stage1: 'Stage 1 — independent review',
+  stage2: 'Stage 2 — peer cross-review',
+  'debate-defense': 'Debate — defense',
+  'debate-revote': 'Debate — re-vote',
+  'tally-provisional': 'Tally (provisional)',
+  tally: 'Tally',
+  'tally-final': 'Tally (final)',
+  chair: 'Chair synthesis',
+  verdict: 'Verdict',
+};
+
+function readDoc(runDir, name) {
+  const rawPath = path.join(runDir, name);
+  if (!fs.existsSync(rawPath)) { return null; }
+  try { return JSON.parse(fs.readFileSync(rawPath, 'utf-8')); }
+  catch (err) { return { parseError: err.message, rawPath }; }
+}
+
+function stageRail(run) {
+  const stages = Array.isArray(run.stages) ? run.stages : [];
+  return stages.filter((s) => s && typeof s === 'object').map((s) => ({
+    name: s.name,
+    label: STAGE_LABELS[s.name] || String(s.name),
+    status: s.status || 'pending',
+    startedAt: s.startedAt || null,
+    completedAt: s.completedAt || null,
+  }));
+}
+
+function costPanel(run, tally) {
+  const stats = tally && Array.isArray(tally.runStats) ? tally.runStats : [];
+  const rows = stats.map((r) => ({
+    model: r.model,
+    role: r.role || (r.wasChair ? 'chair' : 'seat'),
+    status: r.status || 'unknown',
+    durationMs: r.durationMs === undefined ? null : r.durationMs,
+    costDisplay: formatCost(r.usage && r.usage.cost),
+  }));
+  const cost = run.usage && run.usage.cost ? run.usage.cost : null;
+  // v4.4 §8: the run total must not read as exact when any seat is unpriced.
+  // `run.usage.unknownLegs` is the v4.4 field src/council/run.js stamps; a run
+  // written before that (or by any other producer) still carries the count inside
+  // sumWaveUsage's `cost.unpricedLegs`, so read that as the fallback rather than
+  // silently claiming exactness for every historical run on disk.
+  const unknownLegs = run.usage && typeof run.usage.unknownLegs === 'number'
+    ? run.usage.unknownLegs
+    : ((cost && cost.unpricedLegs) || 0);
+  // v4.4 Task 2: a leg whose own cost is `reported` can STILL leave the run total
+  // short — a subagent's child session is billed separately and never enumerated
+  // (`council-wsgate01`: 7/7 legs reported, $0.0215 short, 100% one child session).
+  const subtreeUnknownLegs = run.usage && typeof run.usage.subtreeUnknownLegs === 'number'
+    ? run.usage.subtreeUnknownLegs
+    : ((cost && cost.subtreeUnknownLegs) || 0);
+  const total = formatCost(cost);
+  const suffixes = [];
+  if (unknownLegs > 0) { suffixes.push(`${unknownLegs} unknown`); }
+  if (subtreeUnknownLegs > 0) { suffixes.push(`${subtreeUnknownLegs} subagent subtree`); }
+  return {
+    rows,
+    totalDisplay: suffixes.length > 0 ? `${total} + ${suffixes.join(' + ')}` : total,
+    costAmount: cost && typeof cost.amount === 'number' ? cost.amount : null,
+    // The gauge's guard (workspace-render.js renderGauge): false means "the
+    // percentage below is a LOWER BOUND", so it must render indeterminate.
+    // PREFER the producer's own flag when run.json carries it — recomputing it
+    // from `unknownLegs` alone would silently re-assert exactness for a run whose
+    // writer already determined the total is incomplete for a different reason.
+    costExact: run.usage && typeof run.usage.costExact === 'boolean'
+      ? run.usage.costExact
+      : (unknownLegs === 0 && subtreeUnknownLegs === 0),
+    unknownLegs,
+    subtreeUnknownLegs,
+    maxCost: run.options && typeof run.options.maxCost === 'number' ? run.options.maxCost : null,
+  };
+}
+
+// ⚠️ PRE-FLIGHT (P3): F04's correction is implemented here rather than left as prose.
+// VERIFIED on shipped main (Task 0): `finalize(exitCode, error)` writes `error: error || null`
+// (src/council/run.js:98-100), and `return finalize(degraded.value ? 2 : 0)` (:293) is the ONLY
+// exit-2 path — it passes NO error. Every error-bearing call is `finalize(1, …)`. So on a
+// `status:'partial'` run — precisely the run this panel exists to explain — `run.error` is
+// GUARANTEED null, and the old one-line formula rendered "undefined: undefined".
+// Name the stage instead. Stage status is a closed set (DE-ROT F19): running / complete /
+// skipped / error, and `run-chair.js:114` writes 'error' for a chair that failed after retry +
+// fallback promotion, 'skipped' (:89) for one the cost ceiling skipped.
+function degradedReason(run) {
+  // exit-1 path: the engine wrote a structured {code, message}.
+  if (run.error && run.error.code) { return `${run.error.code}: ${run.error.message}`; }
+  const stages = Array.isArray(run.stages) ? run.stages : [];
+  const failed = stages.find((s) => s && s.status === 'error');
+  if (failed) { return `${STAGE_LABELS[failed.name] || failed.name} stage failed`; }
+  const skipped = stages.find((s) => s && s.status === 'skipped');
+  if (skipped) { return `${STAGE_LABELS[skipped.name] || skipped.name} stage was skipped (cost ceiling)`; }
+  return null;
+}
+
+function verdictPanel(run, verdict) {
+  const reason = degradedReason(run);
+  if (!verdict || verdict.parseError) {
+    return { present: false, overallVerdict: null, tierCounts: null, streetCred: [], decisions: [], reason };
+  }
+  return {
+    present: true,
+    overallVerdict: verdict.overallVerdict === undefined ? null : verdict.overallVerdict,
+    tierCounts: verdict.tierCounts || null,
+    streetCred: Array.isArray(verdict.streetCred) ? verdict.streetCred : [],
+    decisions: (Array.isArray(verdict.findings) ? verdict.findings : [])
+      .filter((f) => f && f.decision)
+      .map((f) => ({ id: f.id, decision: f.decision, applied: f.applied === true })),
+    reason,
+  };
+}
+
+/**
+ * @param {string} project
+ * @param {string} runId (with or without the council- prefix)
+ * @returns {object} RunDetail (see plan Shared contracts)
+ */
+function getRunDetail(project, runId) {
+  const ptr = readPointer(project, runId);
+  if (ptr.error) { return { runId: ptr.runId, error: ptr.error }; }
+  const runDir = ptr.runDir;
+
+  // Outer containment fence (third council-review pass): readPointer's shipped
+  // implementation (src/council/run-state.js:133-139) validates the pointer file's
+  // {runId, runDir} JSON only for truthiness, so a tampered or stale pointer can point
+  // runDir anywhere on disk. Mirrors src/workspace/artifact-guard.js's readRunArtifact
+  // outer fence and electron/ipc-workspace.js's workspace:open-report fence — same
+  // isRealpathContained helper (src/utils/path-fence.js), same check. Own
+  // distinguishable error string: getRunDetail's other error shapes ('run.json missing',
+  // the readPointer-sourced messages) are asserted by name in several suites and must
+  // not collide with this one. Checked BEFORE any read reaches the filesystem, unlike
+  // readRunArtifact (which reads run.json first) — getRunDetail has no allowlist-shaped
+  // reason to read anything from an escaping runDir at all.
+  let realProject, realRunDir;
+  try { realProject = fs.realpathSync(project); }
+  catch (err) { return { runId: ptr.runId, runDir, error: `project unreadable: ${err.message}` }; }
+  try { realRunDir = fs.realpathSync(runDir); }
+  catch (err) { return { runId: ptr.runId, runDir, error: `run dir unreadable: ${err.message}` }; }
+  if (!isRealpathContained(realProject, realRunDir)) {
+    return { runId: ptr.runId, runDir, error: 'run directory escapes project' };
+  }
+
+  const run = readDoc(runDir, 'run.json');
+  if (!run) { return { runId: ptr.runId, runDir, error: 'run.json missing' }; }
+  const tally = readDoc(runDir, 'tally.json');
+  const verdict = readDoc(runDir, 'verdict.json');
+
+  let derived = null;
+  // Computed once, outside the `!run.parseError` guard's block so both the derived model
+  // (artifactCollisions) and the artifacts presence map below reuse the same call.
+  const artifactNames = run.parseError ? [] : artifactAllowlist(run);
+  if (!run.parseError) {
+    const labelMap = run.labelMap && typeof run.labelMap === 'object' ? run.labelMap : {};
+    const tallyOk = tally && !tally.parseError ? tally : null;
+    derived = {
+      schemaSupported: run.schemaVersion === 2,
+      names: buildNamePairs(labelMap),
+      stageRail: stageRail(run),
+      // ⚠️ DE-ROT (F07): 3-arg signature — tierOverride + post-override tier live in verdict.json.
+      matrix: tallyOk ? buildMatrixModel(tallyOk, labelMap, verdict && !verdict.parseError ? verdict : null) : null,
+      cost: costPanel(run, tallyOk),
+      verdictPanel: verdictPanel(run, verdict),
+      // ⚠️ R4 COUNCIL REVIEW (fourth live paid council, major, unanimous): two distinct bench
+      // entries that sanitize to the same artifact name (artifact-guard.js's
+      // artifactAllowlist) is a run-integrity defect — this run directory cannot hold both
+      // models' review/judge files under distinct names, so drillIntoJudge's artifact lookup
+      // would otherwise silently misattribute prose. Surfaced here (rather than only inside
+      // the low-level allowlist helper) so the renderer can warn the user directly.
+      artifactCollisions: artifactNames.collisions || [],
+    };
+  }
+
+  const artifacts = {};
+  const names = artifactNames;
+  for (const name of [...names, 'report.html', 'run.json', 'tally.json', 'verdict.json']) {
+    try {
+      const st = fs.statSync(path.join(runDir, name));
+      artifacts[name] = { present: true, bytes: st.size };
+    } catch {
+      artifacts[name] = { present: false, bytes: 0 };
+    }
+  }
+
+  return { runId: ptr.runId, runDir, run, tally, verdict, artifacts, derived };
+}
+
+module.exports = { getRunDetail, costPanel, TERMINAL_STATUSES, STAGE_LABELS };