amicus 4.2.1 → 4.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.2.1",
+  "version": "4.4.0",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -3,7 +3,52 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
-## [Unreleased]
+## [4.4.0] - 2026-07-26
+
+### Added
+
+- **Council Workspace (GUI)** — third Electron mode `council-workspace`, opened via `amicus watch <councilRunId> --ui` (bare `--ui` opens the project run list). Renders live and historical council runs: stage rail, live per-seat status/tokens/cost (v4.3 data layer, 1.5s/5s poll depending on window focus/visibility), verbatim anonymized Stage-2 packet, tier-colored adjudication matrix with basis counts/thin/override badges, dissent drill-in with prose highlight, chair verdict + street-cred + Stage-4 decisions, cost-by-seat with `--max-cost` gauge. Blind-mode toggle (labels vs models; ON while live, OFF once terminal — a reading aid against anchoring bias, not a security control: the label map is plaintext in `run.json`). Two verbs: confirm-gated Abort (delegates to the engine's own council-aware abort path) and nonced Fold (chair verdict to the launching terminal; no model call). Fully sandboxed first-party page (CSP with no network directive at all, `contextIsolation`, textContent-only rendering of model prose, enforced by a static source scan); read-only against run directories **apart from the Abort verb, which checkpoints the run through the engine's own in-process abort path** — not a direct write from the workspace code itself. `--ui` is interactive-only (`--json` is rejected, not silently ignored).
+- `CdpClient.workspace(port)` e2e factory (`file://` target, port 9225) + a fixture-driven workspace CDP suite.
+
+### Fixed
+
+- **Zero-cost reporting no longer lies about spend.** A leg whose captured token totals were *all zero* used to be priced as `0 × catalog price` and labelled `estimated $0.0000` — an authoritative "this seat was free" for work that had genuinely been billed. Diagnosed against four real paid council runs plus OpenCode's own session database: `council-wsgate02` spent **$0.9859 against a `--max-cost` ceiling of $0.75 (131%)** while Amicus believed $0.3720 and never emitted `COST_EXCEEDED`. Four separate defects, all fixed here:
+  - `resolveLegCost` now gates the estimate on **observed tokens**, not on the mere existence of a price, so a zero-token leg resolves to `{amount: null, source: 'unknown'}`. The v4.2 free-local-provider `$0` tier is unaffected — a local seat still reports real token counts, so it keeps resolving to `estimated ~$0.0000`.
+  - The headless poll loop's fast-path exits (trailing fold marker, SDK `idle`) could break *before* OpenCode stamps `info.tokens`/`info.cost` — measured losing by 155 ms and 29 ms on real paid legs. A bounded, best-effort **post-loop usage re-poll** (≤3 reads, ~1.2 s worst case, usage capture only — never re-mirrors text) now closes that window.
+  - `progress.json`'s usage snapshot was only ever written on `receiving` flushes, i.e. always before finalization — 31 of 35 real legs ended with an all-zero snapshot while `metadata.json` held thousands of tokens, and that snapshot is what the live GUI reads. A **terminal `complete` progress record** now carries the settled usage, and the reader prefers `metadata.json` for any terminal leg.
+  - `amicus spend` and the spend ledger no longer coerce a null cost into a measured-looking `$0.0000`: a model whose rows are all unpriced renders `?`, and `unpricedRows` is reported on `total`, `byModel`, every `group`, and `wasted`.
+- **A leg is no longer declared `complete` while its OpenCode session is still working and billing.** Measured on a real paid run: `council-wsgate02`'s `wsgate02-s1-3` was declared complete on **166 characters** of reasoning preamble, 129 s before its `task` tool call finished, and its session then billed $0.14279 of further parent spend plus a $0.47105 child session — 166 characters were adjudicated as a finished peer review. Root cause was a shape drift, not a logic slip: the mirror modelled a tool call as an Anthropic-style `tool_use` part cleared by a matching `tool_result`, and **OpenCode emits neither** (36 `tool_use` records and 0 `tool_result` records across 35 recorded legs; 5,129 persisted parts resolve to six type names, none of them `tool_result`). So `pendingToolCalls` never cleared for any real leg, tool names never reached `conversation.jsonl`, and the `Task`-subagent log was permanently empty. Tool-call liveness is now keyed on the SDK's real `state.status` vocabulary (`pending`/`running`/`completed`/`error`; terminal = `completed`|`error`), and the completion gates that lack an explicit done-signal defer while a call is still executing. The wait is **bounded** by `AMICUS_TOOL_SETTLE_GRACE_MS` (default 300 s, `0` disables): on exceeding it the leg **completes anyway** — never fails — carrying `toolSettleTimedOut` on its result, its `metadata.json` and its terminal `progress.json` record, plus an error-level log line. A tool part whose status cannot be observed at all is deliberately *not* treated as live, so an unknown shape can never hang a finished leg.
+- **`costExact: true` no longer claims a total is complete when it is not.** `council-wsgate01` reported `costExact: true` while **$0.0215 short** of OpenCode's ledger. Reconciled leg-by-leg: all 7 legs were `source: 'reported'` with real tokens, and **100% of the gap was one unattributed `explore` child session** ($0.021460, parent `wsgate01-s1-2`) — not rounding, not partial usage, not float drift. The predicate was wrong: `costExact` was computed as `unknownLegs === 0`, which asks "did every leg report tokens" — a statement about each leg's *own* session, not about whether the total is the whole bill. A leg that spawns a subagent now carries `subtreeUnknown` on its usage block, `sumWaveUsage` reports `subtreeUnknownLegs`, and `costExact` requires **both** every leg observed *and* no unattributed subtree. Surfaced on `run.json`, the `Notice:` line, the human summary, the workspace total and the `--max-cost` gauge (which goes indeterminate). Subtree-unknown spend still does not trip the ceiling — fail loud, not closed.
+- **`--max-cost` is now threaded into the council pre-flight estimate.** `src/council/run-launch.js` never passed `maxCost` to the transport, so `src/sidecar/fanout.js` fell back to a `cfg.maxCost` key that does not exist and the `budget.js` soft ceiling was inert for every council run — the post-hoc check in `run.js` was the only ceiling, and it can only refuse *after* the money is spent. Each wave is now measured against the **remaining** allowance (ceiling − known spend − outstanding reservations).
+- **The council pre-flight ceiling is now concurrency-safe.** Stage 1 launches its seat wave and its critic wave together under one `Promise.all`, and each launcher read the remaining allowance *before either wave's legs had been recorded* — so both saw the full, unreduced ceiling and both could pass a gate that only one of them fit under. A read is not a claim. The transport now takes an optional `reserveBudget(estimate)` seam (`src/sidecar/fanout-budget.js`, extracted from `runFanout` §1b) which the council answers with a **synchronous** read-and-claim against the allowance no sibling wave has taken — synchronicity is the guarantee, since the event loop cannot interleave two callers inside it. A fixed quota split was rejected as strictly more refusing than the ceiling requires. **When a wave is refused the run continues with a partial bench** — it never rolls back launched waves and never aborts (fail loud, not closed) — but the refusal is announced on stderr, recorded on `run.json` as `budgetRefusals[]`, and degrades the run's exit code to `2`. Stage 1's existing quorum gate still refuses to call a bench of fewer than two reviews a council.
+- **The best-effort usage-settle re-poll can no longer discard a finished leg.** Its `try/catch` covered only the network read; the snapshot inspection that followed it (`mirrorUsageOnly`, `allAssistantUsagePresent`) ran outside the boundary, so a throw there escaped `runHeadless` and destroyed a leg whose answer had already been captured and paid for — the most expensive possible outcome for a path whose whole job is an optional usage top-up. The boundary now covers the entire loop body; a failure stops settling, keeps every dollar already mirrored, and leaves the completion verdict untouched.
+- **`AMICUS_USAGE_SETTLE_POLLS=0` (and friends) now actually disable the feature.** All four v4.4 settle knobs parsed their environment override as `Number(process.env.X) || DEFAULT`, which silently rewrites an explicit `0` — the documented "off" value — back into the default. `AMICUS_USAGE_SETTLE_POLLS`, `AMICUS_USAGE_SETTLE_INTERVAL_MS`, `AMICUS_USAGE_SETTLE_CALL_TIMEOUT_MS` and `AMICUS_TOOL_SETTLE_GRACE_MS` now go through `src/utils/env-num.js`, which honors an explicit numeric value including `0` and falls back only for unset / blank / non-finite. Older knobs (`AMICUS_POLL_INTERVAL_MS`, `AMICUS_STABLE_*_POLLS`, `AMICUS_TOOL_CALL_STALL_MS`, …) deliberately keep the old form: `0` is not a documented escape hatch for any of them and honoring it would busy-loop a poller or disable a stall guard.
+- **Subagent (child-session) spend is now attributed to the leg that spawned it.** A leg that calls the `task` tool spawns a *child* OpenCode session; OpenCode bills it separately, does **not** roll it into the parent session's cost, and amicus never enumerated it — so it was invisible to every total the product prints. Measured across the four recorded paid runs: **$0.492506** ($0.021460 in `wsgate01`, $0.471046 in `wsgate02`). `wsgate01` was the honest limit case — all 7 legs `source: 'reported'`, `unpricedLegs: 0`, `costExact: true`, and the run still 7.1% short, with 100% of the gap in one `explore` child session. `runHeadless` now walks each leg's child sessions at finalization (bounded, cycle-proof, directory-scoped) and the measured spend rolls into the run total, reported separately as `cost.subtreeCost` / `cost.subtreeSessions`. Replayed against the OpenCode oracle, `wsgate01` reconciles **exactly**. A child's price comes from OpenCode's own billing and is never estimated from a catalog — the SDK's session record carries no model id, so an estimate would be a guess. What the walk cannot account for still reports as `subtreeUnknown`, never as zero; conversely, a subtree that WAS fully walked now clears that flag, which the previous `task`-name proxy could never do. A failed walk with no evidence of a subagent at all flags nothing, so an OpenCode build without the `children` endpoint does not mark every leg of every run inexact.
+- **A Stage-1 repair re-prompt now carries the review it is repairing.** When a review's trailing findings JSON failed validation the engine launched a repair solo — a *fresh* session with no memory of the review turn — and handed it the validation **errors without the review those errors were about**. Three of the five paid councils burned a seat on it: `wsgate02`'s `qwen` and `wsgate04`'s `glm` both refused, twice each ("I don't have a previous review to correct"; "the previous review's content was excluded by the caller… I will not fabricate findings"), so a 4-model bench silently adjudicated on 3 while still paying for the fourth's tokens; `costgate01`'s `grok` complied instead, by **inventing a self-referential finding about its own empty output**, which entered `tally.json`, the street-cred rankings and the chair synthesis as `C1` and reached a human's decision. The prompt now embeds, verbatim and uncapped, the text that actually failed — the original review on the first attempt, the previous repair's output on the second, so the errors and the artifact they describe are always the same thing. When there genuinely is no prior text the prompt **says so** and instructs the model to emit an empty `findings` array rather than leaving it to guess.
+
+### Changed
+
+- **Unknown cost fails LOUD, not CLOSED.** A leg whose cost cannot be determined does **not** halt a run and does **not** by itself trip `--max-cost` — the ceiling still trips on known spend only. Instead the uncertainty is made impossible to miss: `run.json`'s `usage` block gains `unknownLegs` + `costExact`, the council run emits a `Notice:` naming the count and stating that real spend is higher, the human summary appends `+ N leg(s) unknown — real spend is at least this much`, `amicus spend` adds an explicit unpriced-rows line, and the workspace's budget gauge switches to an indeterminate (hatched) band with a `≥` readout rather than claiming a percentage it cannot know. Nothing converts uncertainty into a fabricated number in either direction.
+- **`amicus watch <councilRunId>` now prints per-seat rows in the terminal**, not just the stage checklist — each seat's model, status, message count, tokens, cost and stall state, refreshed on the same poll as the stage rail. This is a **behavior change to an existing command**: a plain terminal `amicus watch` on a council run shows materially more than it did on 4.3.0, with no new flag. The Council Workspace GUI and the terminal renderer now read the same per-leg data.
+
+### Security
+
+- **A council pointer file can no longer redirect reads — or writes — outside the project.** A `council-<runId>.json` pointer's `{runId, runDir}` JSON is validated only for truthiness (`src/council/run-state.js`), so a tampered or stale pointer could name any `runDir` on disk. The v4.4 Council Workspace already fenced all four of its pointer-consuming reads against the run dir's realpath; the older CLI/MCP surface behind `amicus_status` / `amicus_abort` / `amicus_list` / `amicus watch` did not, and two of its call sites are worse than a read leak — both crash detection and abort `checkpoint()` **into** `ptr.runDir`, making an unfenced pointer a write primitive at an attacker-chosen path. All of them now resolve and check containment **before touching the filesystem at all**, sharing the one fence implementation (`src/utils/path-fence.js`). A fenced-out pointer resolves to the existing "not a council run" outcome — the same `Session <id> not found in project <cwd>` error `amicus_status`/`amicus_abort` already return for an absent pointer, a skipped row in `amicus_list`, and `kind: 'unknown'` (→ `BAD_SESSION`) for `watch` — so no new error shape, and nothing is read or written from the escaping directory. Nothing legitimate is refused: a real `runDir` is always nested inside the project, enforced at creation time.
+
+## [4.3.0] - 2026-07-24
+
+### Added
+
+- **Observability data layer.** Three file surfaces every consumer polls, no push/IPC/`fs.watch` anywhere: the existing durable snapshots (`metadata.json`/`progress.json`/`wave.json`/council `run.json`, all additively extended), a new append-only `events.jsonl` milestone stream per wave dir / council-run dir, and the composed live doc (the `amicus_status` rollup, stamped `view:'live'` with per-leg read-time `usage`).
+- **`amicus watch <id>`** — live-render any fan-out wave, council run, or session from any terminal, reading only the data layer above (no attach): an in-place refresh table on a TTY, milestone lines (`--plain` / non-TTY), or NDJSON (`--json`). `--interval` controls the poll rate (default 2s, floor 0.5s); exit code maps the run's terminal state (`complete`→0, `partial`→2, else 1). `--ui` registers the flag for the v4.4 Council Workspace GUI (rejects `--json`) — the GUI itself is not shipped in this release.
+- **`--follow` on `fanout` and `council run`** — stream a run's own milestone events to stderr as they happen; stdout's `--json`/human contracts stay byte-identical. On `council run`, `--follow` covers the run's own lifecycle and each stage's boundaries, not the per-leg events inside a stage's internal fan-out sub-wave.
+- **`--on-complete` hook.** CLI: runs a user-authored shell command once a wave/council run reaches a terminal state, with the payload carried via 8 environment variables (`AMICUS_TASK_ID`, `AMICUS_TYPE`, `AMICUS_STATUS`, `AMICUS_EXIT_CODE`, `AMICUS_RESULT_FILE`, `AMICUS_EVENTS_FILE`, `AMICUS_COST`, `AMICUS_PROJECT`) — ids/paths only, never model-generated text; exit-isolated from the run (a non-zero exit or a 60s timeout is a warning only). MCP: only `onComplete: "mcp-notify"` is accepted, a best-effort advisory notification — `exec` is never exposed over MCP.
+- **Failed-leg resilience.** `fanout --retry-failed <waveId>` relaunches only a wave's terminal, non-complete legs as a new linked wave (byte-identical retry from each leg's saved context; `--models` filters which legs retry; the original `wave.json` is never touched). `--fallback` / `--no-fallback` opt into per-leg cheaper-model substitution, off by default, triggered only by a classified rate-limit/overload failure (never timeout or auth) and always recorded loudly (a `leg-fallback` event, an `attempts[]` array, a `fallback` block on the final doc).
+- **Spend visibility & attribution.** `continue`/`resume`/council rows are now recorded in the spend ledger, not just `start`/`fanout` legs, and every row carries attribution (`op`/`status`/`waveId`/`councilRunId`/`councilName`/`project`/`gateway`, plus fallback/retry linkage). `amicus spend` grows a full query surface — `--wave`/`--council`/`--project`/`--model`/`--op`/`--failed`/`--group-by <model|wave|council|project|op|day>`/`--rows` — plus a `wasted` rollup (both `--failed` and `wasted` deliberately exclude rows with no recorded status at all, so a pre-v4.3 ledger row is never counted as a failure that was never actually recorded). A new read-only `amicus_spend` MCP tool (16th tool) mirrors the same flags for MCP-only hosts.
+
+### Notes
+
+- All additive: no schema-breaking changes to v4.0 artifacts. `SPEND_LEDGER_SCHEMA_VERSION` stays `1`; both JSONL ledgers (`spend-ledger.jsonl`, `council-ledger.jsonl`) remain internal, non-envelope files, not published docs. A wave dir / council-run dir now also contains `events.jsonl`.
 
 ## [4.2.1] - 2026-07-23
 

package/README.md

@@ -45,12 +45,14 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 
 ## What is Amicus
 
-One install delivers four things that work together:
+One install delivers six things that work together:
 
 - **The `second-opinion` LLM Council skill.** Structured multi-model review: independent reviews → anonymized peer cross-review → a non-Claude chair verdict → tiered accept/deny decisions. This is the hero.
 - **The `sidecar` chat skill.** Ad-hoc fork/work/fold — spin up one other model in a real window (or headless), work alongside it, fold the summary back.
 - **The `amicus` CLI (with an `am` alias) and an MCP server.** The engine underneath both skills: launches sessions, shares context, runs parallel waves, and exposes the same surface to Claude as MCP tools.
 - **A self-updating model catalog.** Aliases and validation resolve against a live catalog fetched from provider APIs (cached locally), so model names stay current without a hard-coded table.
+- **Observability.** `amicus watch <id>` renders any live or finished run (fan-out or council) from any terminal; `--follow` streams milestones as they happen; `--on-complete` fires a hook when a run lands; `--retry-failed` plus opt-in cheaper-model fallbacks recover dead legs without relaunching the whole wave; `amicus spend` answers "what did this cost, and where" with per-run attribution.
+- **Council Workspace.** `amicus watch <runId> --ui`: a window that shows a council *thinking* — live seats, the anonymized judge packet, the adjudication matrix, dissent drill-in, chair verdict, and cost-by-seat — for both live and historical runs.
 
 Claude is the orchestrator. The council and chat skills run *on top of* the engine; you talk to Claude, and Claude drives Amicus.
 
@@ -313,9 +315,10 @@ amicus update
 | `amicus continue` | Start a new session building on a previous one. |
 | `amicus read` | Output a session's summary / conversation / metadata. |
 | `amicus status <id>` | One-shot status for a session or fan-out wave (human or `--json`; `--wave <id>` alternative spelling). |
+| `amicus watch <id>` | Live-render a fan-out wave, council run, or session from any terminal until it finishes — in-place table on a TTY, `--plain` milestone lines, or `--json` NDJSON; exit code maps the terminal state. `--ui` opens the [Council Workspace](./docs/council.md#council-workspace-gui) window instead (interactive-only, no `--json`). |
 | `amicus models` | List, search, refresh the catalog, or audit aliases. |
 | `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |
-| `amicus spend` | Cross-run cost rollup from the spend ledger — total + per-model spend, tokens, and source mix, most-expensive first (`--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
+| `amicus spend` | Cross-run cost rollup from the spend ledger, with per-run attribution — total + per-model spend, tokens, and source mix, most-expensive first (`--wave`/`--council`/`--project`/`--model`/`--op`/`--failed` filter it, `--group-by` buckets it, `--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
 | `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
 | `amicus provider` | Add/list/test/remove local, OpenAI-compatible providers (LM Studio, Ollama, vLLM) — configured with `--preset` or `--url`, at **$0** marginal cost (`--json` on every subcommand). |
 | `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`, `validate <file>` (findings-block check, exit 0/2/1), `verdict <tally.json> [--decisions <d.json>] [-o <out.json>]` (build + write verdict.json). Presets: `save <name> --models a,b,c`, `list [--json]`, `show <name> [--json]` — see [The Council](#the-council) for the built-in `free`/`budget`/`frontier` benches. |
@@ -348,7 +351,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.2.1",
+  "version": "4.4.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -382,7 +385,7 @@ Full details, the API-key/prefix table, and the migration notice are in **[docs/
 
 ## MCP integration
 
-The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes fifteen tools:
+The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes sixteen tools:
 
 | Tool | What it does |
 |------|--------------|
@@ -401,6 +404,7 @@ The MCP server is auto-registered on install (Claude Code and Claude Desktop / C
 | `amicus_council_stats` | Reviewer-reliability stats from past council runs. |
 | `amicus_verdict` | Build the final council verdict from a tally + decisions; writes `<outDir>/report.html` when `render:true` and `outDir` are given. |
 | `amicus_council_run` | Run the full headless council engine (Stage-1 reviews → anonymized cross-review → tally → chair verdict); returns `{ runId, runDir }`, async. |
+| `amicus_spend` | Read-only cross-run cost rollup from the spend ledger (mirrors the CLI `amicus spend` flags). |
 
 The async pattern is **start → status → read** — `amicus_start`/`amicus_fanout` return immediately, then you poll `amicus_status` and call `amicus_read`; `amicus_wait` collapses that poll loop into one blocking call.
 

package/bin/amicus.js

@@ -127,6 +127,11 @@ async function main() {
         exitCode = await handleSpend(args);
         break;
       }
+      case 'watch': {
+        const { handleWatch } = require('../src/cli-handlers-watch');
+        exitCode = await handleWatch(args);
+        break;
+      }
       case 'provider': {
         const { handleProvider } = require('../src/cli-handlers-provider');
         exitCode = await handleProvider(args);

package/electron/ipc-workspace.js

@@ -0,0 +1,283 @@
+/**
+ * Council Workspace IPC (v4.4 §4.5) — all seven workspace: channels.
+ *
+ * ipc-setup.js registration pattern + DI for tests. Every handler validates
+ * the sender against the workspace window via isPrivilegedSender (M9
+ * belt-and-suspenders, even though this window has one webContents). All
+ * reads are main-process-side; the renderer never sees a filesystem path
+ * except for display. Read-only against runDir (spec §6.2): fold writes to
+ * OUR stdout; abort delegates to the engine's own council-aware path.
+ *
+ * The in-process v4.3/v4.0 seam: require('../src/mcp-server').handlers —
+ * requiring mcp-server does NOT start the server (cli-handlers-status.js:3).
+ */
+'use strict';
+
+const path = require('path');
+const { pathToFileURL } = require('url');
+const { logger } = require('../src/utils/logger');
+const { isPrivilegedSender } = require('./ipc-guard');
+const { isRealpathContained } = require('../src/workspace/artifact-guard');
+
+function defaultDeps() {
+  return {
+    scanCouncilRuns: (...a) => require('../src/workspace/run-scan').scanCouncilRuns(...a),
+    getRunDetail: (...a) => require('../src/workspace/run-detail').getRunDetail(...a),
+    readPointer: (...a) => require('../src/workspace/run-scan').readPointer(...a),
+    readRunArtifact: (...a) => require('../src/workspace/artifact-guard').readRunArtifact(...a),
+    buildFoldText: (...a) => require('../src/workspace/fold-format').buildFoldText(...a),
+    normalizeLive: (...a) => require('../src/workspace/live-normalize').normalizeLive(...a),
+    handlers: () => require('../src/mcp-server').handlers,
+    // Node passes an Error to this callback when the chunk fails to flush
+    // (e.g. a dead parent pipe / closed stdout) — reject on it rather than
+    // resolving unconditionally, or a failed write reports {ok:true} to the
+    // renderer and permanently latches gate.hasCompleted() (code review fix).
+    stdoutWrite: (text) => new Promise((resolve, reject) => {
+      process.stdout.write(text, (err) => (err ? reject(err) : resolve()));
+    }),
+    openExternal: (url) => require('electron').shell.openExternal(url),
+    existsSync: (p) => require('fs').existsSync(p),
+    realpathSync: (p) => require('fs').realpathSync(p),
+  };
+}
+
+/**
+ * Two-flag fold latch (fold.js folded/completed pattern WITHOUT the
+ * close-guard fallback-destroy machinery — a workspace fold does no async
+ * model work, so that failure surface does not apply; spec §7).
+ *
+ * ⚠️ COUNCIL REVIEW R2 (A3): `completed` used to be a single unkeyed boolean —
+ * one successful fold latched the gate for the ENTIRE life of the window, for
+ * every run, not just the one that was actually folded. The renderer supports
+ * navigating to a different run within one open window (openRun with a
+ * dynamic runId; a bare `--ui` launch opens the whole project run list, spec
+ * §4.3/§4.4), so: open run A, Fold (succeeds) -> switch to run B, Fold ->
+ * the old code returned {ok:true, already:true} WITHOUT ever writing
+ * anything for B. Silent wrong-result, not cosmetic: the UI reads "Folded ✓"
+ * for a run that was never written to the launching terminal.
+ *
+ * Completion is now keyed per runId (a Set of runIds that have been
+ * successfully folded), so each DISTINCT run gets its own honest
+ * begin()/hasCompleted() pair. `writing` (in flight) stays a single GLOBAL
+ * flag on purpose: at most one fold write can be in progress at any instant
+ * regardless of which run it is for (there is exactly one stdout stream to
+ * write to), so a second concurrent call — for the SAME run or a different
+ * one — still correctly gets 'fold-in-flight' rather than interleaving two
+ * writes.
+ *
+ * Why per-run, not "reset the whole gate when the active run changes" or
+ * "keep one global one-shot latch and just report it more honestly": the
+ * plan's spec §7 line ("the fold nonce is per-window-launch... one fold
+ * write per launch... a second fold of the SAME run legitimately returns
+ * already:true") was written before multi-run navigation existed and reads
+ * naturally as "don't spam-refold what you already folded" rather than "the
+ * whole window may only ever fold one run, period." Concretely, allowing one
+ * successful fold per DISTINCT run within a single launch is safe: the
+ * workspace's fold-write path (src/sidecar/workspace-window.js) just relays
+ * accumulated stdout live and returns the exit code once the window closes —
+ * it does no first/last-marker disambiguation the way the OLDER headless
+ * model-session flow's findTrailingFoldMarker does (src/headless.js) — and
+ * every fold block is self-identifying (`Session: <runId>`,
+ * src/workspace/fold-format.js), so two distinct runs folded into the same
+ * launch's stdout are unambiguous to whatever reads it. A global
+ * one-shot-per-window latch would instead be a real product regression: it
+ * would make "browse several runs and fold the ones you care about" — the
+ * whole point of the window NOT auto-closing after a fold — impossible
+ * without reopening the workspace for every run after the first.
+ */
+function createFoldGate() {
+  let writing = false;
+  let writingRunId = null;
+  const completedRuns = new Set();
+  let pendingClose = false;
+  return {
+    /** @returns {boolean} true when a write may start for runId */
+    begin(runId) {
+      if (writing || completedRuns.has(runId)) { return false; }
+      writing = true;
+      writingRunId = runId;
+      return true;
+    },
+    /** @returns {boolean} true when a close was blocked during the write */
+    settle({ ok }) {
+      writing = false;
+      if (ok) { completedRuns.add(writingRunId); }
+      writingRunId = null;
+      const p = pendingClose;
+      pendingClose = false;
+      return p;
+    },
+    isWriting() { return writing; },
+    hasCompleted(runId) { return completedRuns.has(runId); },
+    noteBlockedClose() { pendingClose = true; },
+  };
+}
+
+/**
+ * @param {() => object|null} getWindow returns the workspace BrowserWindow
+ * @param {{project: string, nonce: string, ipc?: object, gate?: object, deps?: object}} ctx
+ * @returns {{gate: object}}
+ */
+function registerWorkspaceHandlers(getWindow, ctx) {
+  const { project, nonce } = ctx;
+  const deps = { ...defaultDeps(), ...(ctx.deps || {}) };
+  const ipc = ctx.ipc || require('electron').ipcMain;
+  const gate = ctx.gate || createFoldGate();
+  const fromWorkspace = (event) => isPrivilegedSender(event, getWindow);
+  // ⚠️ CODE REVIEW (task-9 post-approval): settle()'s pendingClose signal used to be
+  // read only on the success path below, so a close blocked while a fold was writing
+  // silently dropped on the two failure paths (settle({ok:false}) at the detail-error
+  // early return and in the outer catch) — the window stayed open with no further
+  // close handler poised to retry until the user clicked X again. All three settle()
+  // call sites must honor a pending close identically.
+  const closeIfPending = (shouldClose) => {
+    if (!shouldClose) { return; }
+    const win = getWindow();
+    if (win && !win.isDestroyed()) { win.close(); }
+  };
+
+  ipc.handle('workspace:list-runs', (event) => {
+    if (!fromWorkspace(event)) { return []; }
+    try { return deps.scanCouncilRuns(project); }
+    catch (err) { logger.error('workspace list-runs failed', { error: err.message }); return []; }
+  });
+
+  ipc.handle('workspace:get-run', (event, runId) => {
+    if (!fromWorkspace(event)) { return { error: 'unauthorized' }; }
+    try { return deps.getRunDetail(project, String(runId)); }
+    catch (err) { return { runId: String(runId), error: err.message }; }
+  });
+
+  ipc.handle('workspace:get-live', async (event, runId) => {
+    if (!fromWorkspace(event)) { return { ok: false, error: 'unauthorized' }; }
+    try {
+      const result = await deps.handlers().amicus_status({ taskId: String(runId) }, project);
+      const text = result && result.content && result.content[0] ? result.content[0].text : '';
+      if (result && result.isError) { return { ok: false, error: String(text).slice(0, 500) }; }
+      let doc;
+      try { doc = JSON.parse(text); } catch { return { ok: false, error: 'unparseable status doc' }; }
+      return deps.normalizeLive(doc);
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  });
+
+  ipc.handle('workspace:read-artifact', (event, runId, name) => {
+    if (!fromWorkspace(event)) { return { error: 'unauthorized' }; }
+    try { return deps.readRunArtifact(project, String(runId), String(name)); }
+    catch (err) { return { error: err.message }; }
+  });
+
+  ipc.handle('workspace:abort-run', async (event, runId) => {
+    if (!fromWorkspace(event)) { return { ok: false, error: 'unauthorized' }; }
+    try {
+      const result = await deps.handlers().amicus_abort({ taskId: String(runId) }, project);
+      const text = result && result.content && result.content[0] ? result.content[0].text : '';
+      return { ok: !(result && result.isError), detail: String(text).slice(0, 2000) };
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  });
+
+  ipc.handle('workspace:fold', async (event, runId) => {
+    if (!fromWorkspace(event)) { return { ok: false, error: 'unauthorized' }; }
+    const runKey = String(runId);
+    // Gate keyed on runKey (council review R2, A3 — see createFoldGate's
+    // docblock): completing run A must not latch a DIFFERENT run B.
+    if (gate.hasCompleted(runKey)) { return { ok: true, already: true }; }
+    if (!gate.begin(runKey)) { return { ok: false, error: 'fold-in-flight' }; }
+    try {
+      const detail = deps.getRunDetail(project, runKey);
+      if (detail.error || !detail.run || detail.run.parseError) {
+        closeIfPending(gate.settle({ ok: false }));
+        return { ok: false, error: detail.error || 'run.json unavailable' };
+      }
+      const chairRead = deps.readRunArtifact(project, runKey, 'chair-output.md');
+      // Distinguish a security fence firing (e.g. the realpath-escape check)
+      // from a benign absence (not written yet) — both fall through to the
+      // same safe fallback body below, but only one of them is worth an
+      // operator's attention (code review fix).
+      if (chairRead && chairRead.error) {
+        logger.warn('Workspace fold: chair-output.md unavailable', { runId: runKey, reason: chairRead.error });
+      }
+      const chairText = chairRead && chairRead.text ? chairRead.text : null;
+      const text = deps.buildFoldText({
+        nonce, project, run: detail.run, tally: detail.tally, verdict: detail.verdict, chairText,
+      });
+      await deps.stdoutWrite(text + '\n');
+      logger.info('Workspace fold completed', { runId: runKey });
+      closeIfPending(gate.settle({ ok: true }));
+      return { ok: true };
+    } catch (err) {
+      closeIfPending(gate.settle({ ok: false }));
+      logger.error('Workspace fold failed', { error: err.message });
+      return { ok: false, error: err.message };
+    }
+  });
+
+  ipc.handle('workspace:open-report', (event, runId) => {
+    if (!fromWorkspace(event)) { return { ok: false, error: 'unauthorized' }; }
+    // ⚠️ DE-ROT (F59): the SHIPPED readPointer (src/council/run-state.js:133-139,
+    // which Task 2's dedupe makes this deps entry resolve to) returns **null** for a
+    // missing/corrupt pointer — it never returns {error}. A bare `ptr.error` throws a
+    // TypeError straight out of the handler, and this was the only one of the seven
+    // with no try/catch. Guard for null AND wrap, like the other six.
+    try {
+      const ptr = deps.readPointer(project, String(runId));
+      if (!ptr || ptr.error) { return { ok: false, error: (ptr && ptr.error) || 'run pointer not found' }; }
+
+      // Containment fence FIRST (council review C1, MAJOR, unanimous; ROUND 4 ORDERING
+      // FIX, third live paid council, blocker-adjacent — this handler is the direct
+      // analogue of the same bug fixed in src/workspace/artifact-guard.js's
+      // readRunArtifact): this handler was the only filesystem-reaching workspace:
+      // channel with no containment check, and the only one that hands a disk-derived
+      // path to a shell verb (openExternal) — ptr.runDir is charset-blind and never
+      // validated beyond truthiness (src/council/run-state.js:133-139). The
+      // existsSync(report) probe used to run BEFORE this fence: read-only and
+      // Boolean, so it never leaked file content, but it let a tampered/stale pointer
+      // use file-EXISTENCE as an out-of-project oracle ahead of any containment check
+      // — the same "resolve+fence before touching the filesystem at all" invariant
+      // every other channel in this file now honours. Resolve+fence runDir first;
+      // only then probe/read anything derived from it.
+      let realProject, realRunDir;
+      try {
+        realProject = deps.realpathSync(project);
+        realRunDir = deps.realpathSync(ptr.runDir);
+      } catch {
+        return { ok: false, error: 'run directory unreadable' };
+      }
+      if (!isRealpathContained(realProject, realRunDir)) {
+        return { ok: false, error: 'run directory escapes project' };
+      }
+
+      const report = path.join(ptr.runDir, 'report.html');
+      if (!deps.existsSync(report)) { return { ok: false, error: 'report.html not written' }; }
+
+      // Inner fence (independent of the one above): report.html must resolve inside
+      // runDir too — a symlinked report.html can't escape the run dir either. Fail
+      // closed on any realpath error (permission, dangling symlink) rather than let
+      // it fall through to openExternal. Generic message (round 4): a readFileSync/
+      // realpathSync failure's err.message embeds the full resolved path it tried to
+      // open — interpolating it here would hand the renderer an internal filesystem
+      // path via the IPC response.
+      let realReport;
+      try {
+        realReport = deps.realpathSync(report);
+      } catch {
+        return { ok: false, error: 'report path unreadable' };
+      }
+      if (!isRealpathContained(realRunDir, realReport)) {
+        return { ok: false, error: 'report escapes run directory' };
+      }
+
+      deps.openExternal(pathToFileURL(realReport).href);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  });
+
+  return { gate };
+}
+
+module.exports = { registerWorkspaceHandlers, createFoldGate };

package/electron/main.js

@@ -79,6 +79,10 @@ const WINDOW_POSITION = process.env.AMICUS_WINDOW_POSITION || 'right';
 // marker. That's safe here because the GUI fold write is exit-code driven, not
 // marker-detected, so an un-advertised fallback nonce can't be exploited.
 const FOLD_NONCE = process.env.AMICUS_FOLD_NONCE;
+// v4.4 Council Workspace mode (AMICUS_MODE=council-workspace). Set by
+// src/sidecar/workspace-window.js; PROJECT defaults to cwd for direct launches.
+const PROJECT = process.env.AMICUS_PROJECT || process.cwd();
+const RUN_ID = process.env.AMICUS_RUN_ID || '';
 
 const OPENCODE_URL = `http://localhost:${OPENCODE_PORT}`;
 
@@ -510,6 +514,27 @@ function createSettingsChildWindow() {
   settingsWin.webContents.on('page-title-updated', (e) => e.preventDefault());
 }
 
+// ============================================================================
+// Council Workspace (v4.4) — third mode; window body lives in workspace-shell.js
+// ============================================================================
+
+function createCouncilWorkspace() {
+  const { createWorkspaceWindow } = require('./workspace-shell');
+  const { registerWorkspaceHandlers, createFoldGate } = require('./ipc-workspace');
+  const { generateFoldNonce } = require('../src/utils/fold-marker');
+  const gate = createFoldGate();
+  registerWorkspaceHandlers(() => mainWindow, {
+    project: PROJECT,
+    nonce: FOLD_NONCE || generateFoldNonce(),
+    gate,
+  });
+  mainWindow = createWorkspaceWindow({ runId: RUN_ID, gate, headless: !!process.env.AMICUS_HEADLESS_TEST });
+  mainWindow.on('closed', () => {
+    mainWindow = null;
+    app.quit();
+  });
+}
+
 // ============================================================================
 // App Lifecycle
 // ============================================================================
@@ -523,6 +548,8 @@ app.whenReady().then(() => {
 
   if (MODE === 'setup') {
     createSetupWindow().catch((err) => { logger.error('createSetupWindow failed', err); });
+  } else if (MODE === 'council-workspace') {
+    createCouncilWorkspace();
   } else {
     createAmicusWindow();
   }

package/electron/preload-workspace.js

@@ -0,0 +1,40 @@
+/**
+ * Council Workspace Preload — minimal typed IPC bridge (v4.4 §4.2/§4.5).
+ *
+ * The workspace page loads via loadFile (a real file:// origin), so
+ * contextBridge works under FULL sandbox — no data:-URL workaround needed
+ * (docs/electron-testing.md Known Limitations; the setup wizard only works
+ * because it runs sandbox:false, a posture this page must not inherit: it
+ * renders untrusted model prose, the H9 surface).
+ *
+ * Exposes exactly one function. No openExternal bridge, no listeners.
+ * Unknown channel → throw (preload-setup.js pattern).
+ *
+ * ⚠️ DE-ROT (F30): this header used to name the banned electron module (the
+ * one preload-setup.js:9 imports for openExternal). Step 1 asserts
+ * expect(SRC).not.toContain(...) against the RAW file source — comments
+ * included — so that word here made Task 7 fail its own test. Never let the
+ * literal token appear anywhere in this file. Step 4's "PASS (3 tests)" is
+ * correct only with the reworded line above.
+ */
+const { contextBridge, ipcRenderer } = require('electron');
+
+const ALLOWED_CHANNELS = [
+  'workspace:list-runs',
+  'workspace:get-run',
+  'workspace:get-live',
+  'workspace:read-artifact',
+  'workspace:abort-run',
+  'workspace:fold',
+  'workspace:open-report',
+];
+
+contextBridge.exposeInMainWorld('amicusWorkspace', {
+  /** Invoke an allowlisted workspace IPC channel. */
+  invoke: (channel, ...args) => {
+    if (!ALLOWED_CHANNELS.includes(channel)) {
+      throw new Error(`IPC channel not allowed: ${channel}`);
+    }
+    return ipcRenderer.invoke(channel, ...args);
+  },
+});

package/electron/workspace-shell.js

@@ -0,0 +1,85 @@
+/**
+ * Council Workspace window (v4.4 §4.1/§4.2) — the third Electron mode's
+ * BrowserWindow. One window, no WebContentsView split: the workspace is a
+ * single first-party page. Extracted from main.js (grandfathered size) so
+ * the posture is source-testable.
+ *
+ * H9 posture: this page renders untrusted model prose, so it is the MOST
+ * locked-down page in the app — full sandbox, minimal preload, CSP in the
+ * page itself, and it never navigates or opens windows.
+ *
+ * Close semantics (spec §7 resolved Q3): NO auto-fold on close — closing a
+ * viewer discards nothing (all artifacts are on disk). The only guard is the
+ * in-flight fold-write latch supplied by ipc-workspace's gate.
+ */
+'use strict';
+
+const path = require('path');
+const { BrowserWindow } = require('electron');
+const { TOKENS } = require('../src/design/tokens');
+// ⚠️ DE-ROT (F31): shipped guard for exactly this show:false hazard — reuse, don't
+// re-invent (electron/load-failsafe.js:27, paired with show:false at main.js:210-232).
+const { attachLoadFailsafe } = require('./load-failsafe');
+const { logger } = require('../src/utils/logger');
+
+const ICON_PATH = path.join(__dirname, 'assets', 'icon.png');
+
+/**
+ * @param {{runId?: string, gate: {isWriting: () => boolean, noteBlockedClose: () => void}, headless?: boolean}} opts
+ * @returns {BrowserWindow}
+ */
+function createWorkspaceWindow({ runId, gate, headless }) {
+  const win = new BrowserWindow({
+    width: 1100, height: 800, minWidth: 860, minHeight: 600,
+    show: false,
+    frame: true, backgroundColor: TOKENS.bg,
+    title: 'Amicus Council Workspace',
+    icon: ICON_PATH,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload-workspace.js'),
+      contextIsolation: true, nodeIntegration: false, sandbox: true,
+    },
+  });
+
+  win.webContents.on('will-navigate', (event) => { event.preventDefault(); });
+  win.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
+  win.webContents.on('page-title-updated', (e) => e.preventDefault());
+
+  // ⚠️ DE-ROT (F31): attach BEFORE loadFile. onFail shows the window anyway (so the
+  // user sees an empty-but-present shell instead of nothing) and logs the reason;
+  // default timeout is 15s (load-failsafe.js:19). No buildLoadErrorHTML here — the
+  // workspace page is first-party and CSP-locked, so just surface + log.
+  const failsafe = attachLoadFailsafe({
+    webContents: win.webContents,
+    onFail: ({ reason, errorCode, errorDescription, validatedURL }) => {
+      logger.error('Council Workspace page failed to load', {
+        reason, errorCode, errorDescription, validatedURL, runId: runId || ''
+      });
+      if (!headless && !win.isDestroyed()) { win.show(); }
+    },
+  });
+
+  // ⚠️ CODE REVIEW: loadFile() rejects on load failure (and, until Task 11 lands
+  // workspace-ui/index.html, on EVERY launch). The failsafe above already surfaces
+  // and logs the failure, so swallow the rejection itself rather than leaving an
+  // unhandled rejection in the main process (precedent: main.js's own
+  // .loadURL(...).catch(() => {})).
+  win.loadFile(path.join(__dirname, 'workspace-ui', 'index.html'), { query: { runId: runId || '' } })
+    .catch(() => {});
+
+  win.once('ready-to-show', () => {
+    failsafe.cancel(); // disarm on the success path
+    if (!headless) { win.show(); }
+  });
+
+  win.on('close', (event) => {
+    if (gate && gate.isWriting()) {
+      event.preventDefault();
+      gate.noteBlockedClose();
+    }
+  });
+
+  return win;
+}
+
+module.exports = { createWorkspaceWindow };