amicus 4.3.0 → 4.4.0

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,223 @@
+/**
+ * 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').
+ */
+const TERMINAL_STATUSES = ['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', '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 };

package/src/workspace/run-scan.js

@@ -0,0 +1,148 @@
+/**
+ * Council Workspace — run discovery (v4.4 spec §4.3 / §5.1).
+ *
+ * Walks the project sessions dir for v4.0 council pointer files
+ * (`council-<runId>.json` = {runId, runDir}) and builds run-list rows from a
+ * shallow, defensive read of run.json (+ verdict.json for the overallVerdict
+ * chip). Strictly read-only (§6.2). Unreadable pointers/runs come back as
+ * {runId, error} rows — this module never throws on bad input.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { formatCost } = require('../utils/pricing');
+// ⚠️ DE-ROT (F25): v4.0 module (not v4.3) — safe for Phase 1. Single source of truth
+// for reading/validating council pointer files; do not re-parse them here.
+const runState = require('../council/run-state');
+// Same constant run-state.js itself imports (src/council/run-state.js:20), so a
+// future rename can't silently desync this module's walk from its pointer reads.
+const { SESSIONS_DIR } = require('../session-manager');
+// ⚠️ THIRD COUNCIL-REVIEW PASS: readPointer (below) only validates {runId, runDir}
+// for truthiness — a tampered/stale pointer can point runDir anywhere on disk. This
+// is the shared realpath-containment primitive (also used by artifact-guard.js's
+// readRunArtifact and run-detail.js's getRunDetail); it lives in its own leaf module
+// specifically so this file can require it without creating a cycle — artifact-guard.js
+// already requires THIS file for readPointer.
+const { isRealpathContained } = require('../utils/path-fence');
+
+// ⚠️ DE-ROT (F25): widened from /^council-([0-9a-f]{8})\.json$/ to match the shipped
+// walker's pattern (src/council/run-state.js:148) so ids that are not 8 hex still list.
+const POINTER_RE = /^council-([a-zA-Z0-9_-]{1,64})\.json$/;
+
+// Same character class as POINTER_RE's capture group / run-state.js:148's enumeration
+// pattern. readPointer() below is a DIRECT lookup keyed on caller-supplied runId (unlike
+// the POINTER_RE walk above, which only ever sees filenames readdirSync already returned)
+// — without this check a runId containing '/', '..', or backslashes reaches
+// runState.readPointer's `council-${runId}.json` path.join unfiltered and can collapse
+// out of the sessions dir entirely (Task 4 review finding: traversal via unvalidated runId).
+const RUN_ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+
+function sessionsDir(project) {
+  return path.join(project, '.claude', SESSIONS_DIR);
+}
+
+function readJson(file) {
+  try { return { doc: JSON.parse(fs.readFileSync(file, 'utf-8')) }; }
+  catch (err) { return { error: err.message }; }
+}
+
+/** Best-effort sort timestamp: run.json createdAt || first stage start || pointer mtime. */
+function startedAtOf(run, pointerPath) {
+  if (run) {
+    if (run.createdAt) { return run.createdAt; }
+    const s0 = Array.isArray(run.stages) && run.stages[0];
+    if (s0 && s0.startedAt) { return s0.startedAt; }
+  }
+  try { return fs.statSync(pointerPath).mtime.toISOString(); } catch { return null; }
+}
+
+/**
+ * Resolve a council runId to its run dir via the pointer file.
+ * Accepts the id with or without the `council-` prefix (v4.0 readPointer parity).
+ * ⚠️ DE-ROT (F25): thin ADAPTER over the shipped src/council/run-state.js:134
+ * readPointer — that one already strips the prefix (:119) and validates
+ * {runId, runDir}, but returns null. This wrapper is the ONLY place that turns
+ * null into the {runId, error} row the workspace run list renders (§5.1).
+ * @returns {{runId: string, runDir: string} | {runId: string, error: string}}
+ */
+function readPointer(project, runId) {
+  const id = String(runId).replace(/^council-/, '');
+  if (!RUN_ID_RE.test(id)) { return { runId: id, error: 'invalid runId' }; }
+  const ptr = runState.readPointer(project, id);
+  if (!ptr) { return { runId: id, error: 'pointer missing, unreadable, or invalid' }; }
+  return { runId: id, runDir: ptr.runDir };
+}
+
+/**
+ * @param {string} project absolute project dir (AMICUS_PROJECT)
+ * @returns {Array<object>} RunRow[] sorted startedAt desc; error rows inline.
+ */
+function scanCouncilRuns(project) {
+  let names = [];
+  try { names = fs.readdirSync(sessionsDir(project)); } catch { return []; }
+  const rows = [];
+  for (const name of names) {
+    const m = POINTER_RE.exec(name);
+    if (!m) { continue; }
+    const pointerPath = path.join(sessionsDir(project), name);
+    const ptr = readPointer(project, m[1]);
+    if (ptr.error) {
+      rows.push({ runId: m[1], runDir: null, error: ptr.error, pointerPath, startedAt: startedAtOf(null, pointerPath) });
+      continue;
+    }
+
+    // Outer containment fence (third council-review pass): mirrors artifact-guard.js's
+    // readRunArtifact / run-detail.js's getRunDetail — same isRealpathContained helper,
+    // same check. This feeds the GUI run list (spec §5.1), so a fenced-out pointer MUST
+    // degrade to an error row exactly like the dangling-pointer/unreadable-run.json cases
+    // below rather than throw — one bad pointer must never blank the whole run list.
+    let realProject, realRunDir;
+    try {
+      realProject = fs.realpathSync(project);
+      realRunDir = fs.realpathSync(ptr.runDir);
+    } catch (err) {
+      rows.push({
+        runId: m[1], runDir: ptr.runDir, error: `run dir unreadable: ${err.message}`,
+        pointerPath, startedAt: startedAtOf(null, pointerPath),
+      });
+      continue;
+    }
+    if (!isRealpathContained(realProject, realRunDir)) {
+      rows.push({
+        runId: m[1], runDir: ptr.runDir, error: 'run directory escapes project',
+        pointerPath, startedAt: startedAtOf(null, pointerPath),
+      });
+      continue;
+    }
+
+    const r = readJson(path.join(ptr.runDir, 'run.json'));
+    if (r.error) {
+      rows.push({ runId: m[1], runDir: ptr.runDir, error: `run.json: ${r.error}`, pointerPath, startedAt: startedAtOf(null, pointerPath) });
+      continue;
+    }
+    const run = r.doc;
+    const row = {
+      runId: run.runId || m[1],
+      runDir: ptr.runDir,
+      status: run.status || 'unknown',
+      startedAt: startedAtOf(run, pointerPath),
+      completedAt: run.completedAt || null,
+      bench: Array.isArray(run.bench) ? run.bench : [],
+      chair: run.chair || null,
+      costDisplay: formatCost(run.usage && run.usage.cost),
+      tierCounts: null,
+      overallVerdict: null,
+    };
+    const v = readJson(path.join(ptr.runDir, 'verdict.json'));
+    if (!v.error && v.doc) {
+      row.overallVerdict = v.doc.overallVerdict === undefined ? null : v.doc.overallVerdict;
+      row.tierCounts = v.doc.tierCounts || null;
+    }
+    rows.push(row);
+  }
+  rows.sort((a, b) => String(b.startedAt || '').localeCompare(String(a.startedAt || '')));
+  return rows;
+}
+
+module.exports = { scanCouncilRuns, readPointer, POINTER_RE };