cool-workflow 0.1.78

package/docs/multi-agent-trust-policy-audit.7.md

@@ -0,0 +1,154 @@
+# Multi-Agent Trust / Policy / Audit
+
+CW v0.1.22 extends the existing trust-audit layer with first-class
+multi-agent policy, provenance, blackboard write audit, and judge rationale.
+It does not introduce a second audit subsystem.
+CW v0.1.24 includes these trust projections in eval/replay comparison so
+missing provenance, changed policy violations, or missing judge rationale fail
+the regression gate.
+
+## Model
+
+Multi-agent trust state is plain JSON attached to existing records:
+
+- `AgentRole.policy`
+- `AgentGroup.policy`
+- `AgentMembership.policy`
+- blackboard message `provenance`
+- candidate score and selection audit links
+- append-friendly trust events in `.cw/runs/<run-id>/audit/events.jsonl`
+
+Policies describe explicit authority:
+
+- allowed blackboard topic ids
+- allowed write operations: `message`, `context`, `artifact`, `snapshot`,
+  `coordinator-decision`
+- allowed candidate operations: `register`, `score`, `select`
+- allowed judge operations: `verdict`, `rationale`, `panel-decision`
+- sandbox profile hints
+- required evidence refs for privileged actions
+- denied operations and reasons
+
+Missing policy, missing role authority, out-of-scope topics, missing evidence,
+or missing judge rationale fail closed and create audit records.
+
+## Audit Events
+
+The existing audit log records multi-agent dimensions with stable ids:
+
+- `multi-agent.role-policy`
+- `multi-agent.permission`
+- `blackboard.write`
+- `blackboard.message-provenance`
+- `judge.rationale`
+- `judge.panel-decision`
+- `policy.violation`
+
+Events carry ids such as `multiAgentRunId`, `agentRoleId`, `agentGroupId`,
+`agentMembershipId`, `agentFanoutId`, `agentFaninId`, blackboard record ids,
+candidate/score/selection/commit ids, topology ids, `sandboxProfileId`, and
+`policyRef` when relevant.
+
+Audit events do not copy large blackboard bodies. Message provenance stores
+author kind/id, role/group/membership/worker ids when known, source, linked
+evidence refs, parent message ids, topic scope, a body hash, and a short
+summary.
+
+## Blackboard Writes
+
+Every blackboard write is audited:
+
+- topic create/update
+- message post
+- context put/supersede/conflict
+- artifact add
+- snapshot create
+- coordinator decision
+
+The audit record says who wrote, under which role or membership, which policy
+allowed or denied it, what evidence was cited, what record changed, and whether
+the write was accepted, denied, superseded, conflicting, or blocked.
+
+Denied writes are rejected before state mutation and are visible through
+`policy.violation` and `blackboard.write` audit projections.
+
+## Judge Rationale
+
+Judge-panel scoring requires evidence and rationale. Panel selection requires
+score evidence and chair rationale. Accepted judge and panel records cite the
+score, candidate, evidence refs, role policy, and parent audit events.
+
+Missing rationale or evidence blocks score, selection, fanin readiness, and
+verifier-gated commit readiness where those gates depend on judge evidence.
+
+## CLI
+
+Existing commands remain compatible:
+
+```bash
+node scripts/cw.js audit summary <run-id>
+node scripts/cw.js audit provenance <run-id>
+node scripts/cw.js multi-agent status <run-id>
+node scripts/cw.js multi-agent evidence <run-id>
+```
+
+Focused views:
+
+```bash
+node scripts/cw.js audit multi-agent <run-id>
+node scripts/cw.js audit policy <run-id>
+node scripts/cw.js audit role <run-id> <role-id>
+node scripts/cw.js audit blackboard <run-id>
+node scripts/cw.js audit judge <run-id>
+```
+
+Use `--json` or `--format json` for deterministic machine output.
+
+Human output includes stable panels:
+
+- Multi-Agent Trust
+- Role Policies
+- Permission Decisions
+- Blackboard Write Audit
+- Message Provenance
+- Judge Rationales
+- Policy Violations
+- Next Action
+
+## MCP
+
+MCP parity tools:
+
+- `cw_audit_multi_agent`
+- `cw_audit_policy`
+- `cw_audit_role`
+- `cw_audit_blackboard`
+- `cw_audit_judge`
+
+The older audit tools remain available:
+
+- `cw_audit_summary`
+- `cw_audit_worker`
+- `cw_audit_provenance`
+- `cw_audit_attest`
+- `cw_audit_decision`
+
+## Operator Questions
+
+The combined `multi-agent status`, `multi-agent evidence`, `report --show`,
+`audit summary`, and `audit provenance` views answer:
+
+- Which role was allowed to do this?
+- Which blackboard message came from which role, member, or worker?
+- Which write was denied and why?
+- Which judge rationale was accepted?
+- Why was this selected result trusted?
+
+## Regression
+
+`test/multi-agent-trust-policy-audit-smoke.js` creates a judge-panel run with
+allowed and denied blackboard writes, message provenance, role/membership/worker
+links, accepted judge rationale, missing-rationale and missing-evidence failure
+paths, CLI output assertions, MCP parity assertions, report assertions, and
+audit provenance assertions.
+0.1.51

package/docs/node-snapshot-diff-replay.7.md

@@ -0,0 +1,135 @@
+# Node Snapshot / Diff / Replay
+
+CW v0.1.35 adds Node Snapshot / Diff / Replay: per-NODE granularity over the
+v0.1.23 eval/replay harness. Before v0.1.35 the harness worked only at RUN/SUITE
+granularity — `createMultiAgentReplaySnapshot(run)` captured a whole run; there
+was no way to snapshot, fingerprint, diff, or replay a single `StateNode`. This
+release adds that, reusing the harness's normalize/stable-stringify discipline and
+the v0.1.25 fingerprint/freshness pattern — without forking `StateNode`, the eval
+harness, or the run-state schema (all additive).
+
+The discipline is the same base-system separation used elsewhere: the mechanism
+captures/diffs/replays one node by id; nothing decides which node "matters".
+
+## Snapshot — derived + fingerprinted
+
+A `NodeSnapshot` is a DERIVED projection of one `StateNode`: its body is normalized
+(timestamps/paths stripped via the eval harness's `normalizeValue`), so it is
+byte-stable across captures of the same logical state. It carries a
+`sourceFingerprint` — sha256 over the RAW node (`id:status:updatedAt` + artifact
+and evidence ids/paths) — so any transition flips it.
+
+```text
+node snapshot <run-id> <node-id> [--json]
+```
+
+Persisted under `<run>/nodes/snapshots/<node-id>/<snapshot-id>.json`; the source
+`<run>/nodes/<id>.json` stays the truth. The `snapshot-id` is content-addressed
+(`snap-<node>-<fingerprint>`), so re-snapshotting an unchanged node is idempotent.
+
+## Freshness — fail closed on drift
+
+Every load recomputes the fingerprint from the current source and emits a
+freshness verdict:
+
+- `valid` — source matches the snapshot.
+- `stale` — the source node changed since capture.
+- `absent` — the node, or a referenced artifact path, is gone/unreadable.
+
+`stale` and `absent` both REFUSE diff/replay with a structured `NodeSnapshotError`
+naming the divergence — never a silent stale replay, never a best-effort partial.
+
+## Diff — stable + structural
+
+```text
+node diff <run-id> <baseline-snapshot-id> <candidate-snapshot-id> [--json]
+```
+
+Per-section (`status`/`inputs`/`outputs`/`artifacts`/`evidence`/`errors`/`links`/
+`metadata`) `added|removed|changed|same`, ordered deterministically by the same
+`stableStringify` the eval comparison uses. Byte-identical across repeated runs.
+
+## Replay — isolated + deterministic
+
+```text
+node replay <run-id> <snapshot-id> [--json]
+```
+
+Reconstructs the normalized node from the snapshot with `now` INJECTED — no
+ambient `new Date()` in the deterministic payload. The result carries an
+`outputFingerprint` over the normalized body, so two replays of one snapshot are
+byte-identical (only `replayedAt`/`replayId`, which are now-derived, differ).
+Replaying a `stale`/`absent` snapshot fails closed.
+
+## Verify — replay vs source
+
+```text
+node verify <run-id> <replay-id> [--json]
+```
+
+Compares a replay to a FRESH snapshot of the source node and emits a pass/fail
+verdict plus findings in the eval harness's `severity/category/reason/baselineRef/
+replayRef` shape.
+
+## Surfaces & Compatibility
+
+`node.snapshot`/`node.diff`/`node.replay`/`node.replay.verify` are declared in the
+capability registry as `surface: "both"`, so `cw node <verb> --json` and the
+`cw_node_*` MCP tools render one core (`src/node-snapshot.ts`). Additive: no change
+to `StateNode`, `STATE_NODE_SCHEMA_VERSION`, the run-state schema, the pipeline
+contract, or existing eval-suite artifacts; pre-0.1.35 runs and snapshots stay
+loadable. Exporting the previously-private eval-harness helpers
+(`normalizeValue`/`stableStringify`/`lines`) and `fingerprintStrings` is purely
+additive and changes no behavior.
+
+## See Also
+
+state-node(7), multi-agent-eval-replay-harness(7), state-explosion-management(7),
+cli-mcp-parity(7)
+
+## Contract Migration Tooling (v0.1.36)
+
+first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
+
+## Control-Plane Scheduling (v0.1.37)
+
+priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
+
+## Agent Delegation Drive (v0.1.38)
+
+spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+
+## Run Retention & Provable Reclamation (v0.1.39)
+
+tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
+
+## Durable State & Locking (v0.1.40)
+
+atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+
+## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
+
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
+
+## Robust Result Ingest (v0.1.42)
+
+capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
+
+## No-False-Green Gate & Launch Prep (v0.1.43)
+
+Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+
+## Release-Gate Determinism & Agents Vendor (v0.1.44)
+
+Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
+
+## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
+
+Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+0.1.51
+
+0.1.76
+
+0.1.77
+
+0.1.78

package/docs/observability-cost-accounting.7.md

@@ -0,0 +1,194 @@
+# Observability + Cost Accounting
+
+CW v0.1.31 adds Observability + Cost Accounting: time/duration, failure rate,
+verifier pass rate, candidate acceptance rate, and token/cost — all DERIVED from
+the run state CW already keeps. Before v0.1.31 there was no metrics module and no
+token or cost field anywhere; run state already carried `createdAt`/`updatedAt`/
+`completedAt`/`dispatchedAt` and outcome statuses on tasks, workers, verifier
+nodes, candidates, memberships, and feedback. This release projects those into a
+report — and adds an additive, host-attested usage record so cost can be
+accounted honestly — without changing the `ResultEnvelope` schema and without
+taking ownership of source truth.
+
+The design follows the same base-system observability philosophy as
+[State Explosion Management](state-explosion-management.7.md) and the
+[Run Registry / Control Plane](run-registry-control-plane.7.md):
+
+- the per-run `.cw/runs/<id>/state.json` is the SINGLE source of truth
+- metrics are a DERIVED projection of source records, never a separate database
+- no telemetry pipeline, no background collector daemon, no hidden counters
+- plain files, stable JSON, deterministic output
+- fail closed: a rate over zero samples is `n/a`, never a fabricated 0%/100%
+- cost is ATTESTED, never measured or fabricated; absent usage is `unreported`
+- backward compatible; usage/cost fields are additive and optional
+
+## Derived, not a telemetry pipeline
+
+Every number is a projection of existing durable state:
+
+- durations come from recorded timestamps — `dispatchedAt`→`completedAt` for
+  tasks, `createdAt`→worker output `recordedAt` for workers, `createdAt`→
+  `updatedAt` for the run;
+- the failure rate pools failed/rejected workers, failed memberships, failed
+  un-worker-backed tasks, and unresolved (`open`/`tasked`) feedback over the
+  total of those samples;
+- the verifier pass rate counts `verifier` state nodes whose status is a pass
+  (`verified`/`committed`) against decided gates (pass + `failed`/`rejected`/
+  `blocked`); pending/running gates are undecided and excluded;
+- the candidate acceptance rate counts `selected`/`verified` candidates over all
+  candidate records.
+
+There is no metrics store. `deriveMetricsReport(run, { now, policy })` is a PURE
+function of one run's state, an injected `now`, and an optional pricing policy.
+The only now-derived field is `generatedAt`; durations are computed from recorded
+timestamps, so a report over a fixed snapshot is byte-reproducible (eval/replay
+agnostic). The per-run report is persisted as a rebuildable, fingerprinted
+snapshot under `.cw/runs/<id>/metrics/metrics-report.json`; the cross-repo
+summary reports each run's snapshot freshness as `valid|stale|absent` against
+current source — fail closed, exactly like the registry.
+
+## A counter you cannot trust is worse than none
+
+Each rate is a `RateMetric` carrying `state` (`ok`/`n/a`), `count`, `total`,
+`rate`, and per-bucket sample counts. Over zero samples the state is `n/a` and
+`count`/`rate` are `null` — never `0`. No divide-by-zero, no partial-data rate
+presented as complete. Sample counts and buckets accompany every rate so a reader
+can audit the numerator and denominator.
+
+## Cost is attested, never measured or fabricated
+
+CW does not call the model; the host/worker does. Token usage is recorded as
+HOST-ATTESTED provenance — a `UsageRecord` accepted on the existing intake path
+and stored on the task or worker record (never on `ResultEnvelope`):
+
+```
+cw result <run-id> <task-id> <file> \
+  --usage-input-tokens 12000 --usage-output-tokens 3400 \
+  --usage-model claude-opus-4-8 --usage-source host-attested
+cw worker output <run-id> <worker-id> <file> --usage-input-tokens N --usage-output-tokens M --usage-model ID
+```
+
+CW records what the host attests, verbatim, and synthesizes nothing. When the
+host reports no usage the value is an explicit `unreported` — never `0`, never a
+silent guess. The report surfaces `usage.coverage` (the fraction of work units
+carrying attested usage) and `usage.unreportedUnits` so the gap is visible.
+
+A monetary figure is `attested` ONLY when derived from attested usage × a
+recorded pricing policy with an EXACT model match. When a model is priced by the
+policy's `defaultPrice` fallback, that portion is a SEPARATE `estimated` figure
+and the cost `state` becomes `estimated`; the two USD figures are never conflated
+into one. Cost states:
+
+- `attested` — every attested model exact-matched a policy entry;
+- `estimated` — some attested usage was priced by the policy default/fallback;
+- `unpriced` — attested usage present but no policy entry (and no default);
+- `unreported` — no attested usage to price.
+
+## Mechanism vs policy: pricing is data
+
+The runtime is MECHANISM: it records attested usage and derives rates/durations.
+The pricing table is POLICY — supplied as DATA (`CostPolicy`), not baked into the
+kernel. The same attested usage yields different cost reports under different
+pricing without touching the runtime. A bundled EXAMPLE policy lives at
+`manifest/pricing.policy.json` (USD per 1e6 tokens, an editable starting point —
+not a live price feed); pass `--pricing <path>` to use your own, or
+`--pricing default` for the bundled example. With no policy supplied, cost is
+`unpriced`/`unreported`, never guessed.
+
+## One source, every surface
+
+The metrics verbs are declared once in `src/capability-registry.ts`, so the CLI
+and MCP surfaces are two renderings of one core (`src/observability.ts`) and pass
+the v0.1.27 parity gate — `cw <cmd> --json` is byte-identical to `cw_<tool>`
+(durations are integers from recorded timestamps; only the ISO `generatedAt` is
+now-derived and neutralized by the parity probe). The v0.1.30 Workbench renders a
+read-only metrics panel from the same payload, showing coverage and
+`unreported`/`n/a` honestly — it shows nothing the CLI/MCP cannot.
+
+## Commands
+
+- `cw metrics show <run-id>` — the derived per-run report: durations, the three
+  rates with sample counts, attested usage with coverage, and cost. `--json` for
+  the canonical payload; `--pricing <path>|default` to price attested usage.
+- `cw metrics summary` — the cross-repo rollup over the v0.1.28 run registry:
+  pooled rates, summed attested usage/cost with coverage, and per-app and
+  per-backend breakdowns. `--scope repo|home`; unreadable runs are counted
+  (`unreadableRuns`), never silently dropped.
+
+MCP hosts call `cw_metrics_show` and `cw_metrics_summary` with the identical
+payloads. Old runs load and report `unreported` cost while still yielding correct
+time and rate metrics from their existing timestamps and outcomes.
+
+This document targets CW 0.1.31.
+
+
+## Team Collaboration (v0.1.32)
+
+v0.1.32 adds Team Collaboration: a host-attested actor and append-only
+approvals/rejections/comments/handoffs provenance-linked to a durable target,
+plus a review gate that STACKS ON the verifier gate — required approvals from
+authorized roles, enforced inside `resolveCommitGate` AFTER the verifier checks
+and never instead of them, failing closed on quorum/authority/self-approval and
+recording who approved the very artifact that shipped. Policy (required approvals,
+authorized roles, self-approval) is data, default off (pre-v0.1.32 behavior
+unchanged). The verbs are parity-gated and render read-only in the v0.1.30
+Workbench. See [Team Collaboration](team-collaboration.7.md).
+
+## Release Tooling (v0.1.33)
+
+the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a de-duplicated release gate. See release-tooling(7).
+
+## Real Execution Backend Integrations (v0.1.34)
+
+container/remote/ci backends really execute (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is unavailable. See real-execution-backends(7).
+
+## Node Snapshot / Diff / Replay (v0.1.35)
+
+per-node snapshot, structural diff, and isolated deterministic replay over StateNode, reusing the v0.1.23 eval harness; fail-closed on source drift (valid|stale|absent). See node-snapshot-diff-replay(7).
+
+## Contract Migration Tooling (v0.1.36)
+
+first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
+
+## Control-Plane Scheduling (v0.1.37)
+
+priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
+
+## Agent Delegation Drive (v0.1.38)
+
+spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+
+## Run Retention & Provable Reclamation (v0.1.39)
+
+tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
+
+## Durable State & Locking (v0.1.40)
+
+atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+
+## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
+
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
+
+## Robust Result Ingest (v0.1.42)
+
+capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
+
+## No-False-Green Gate & Launch Prep (v0.1.43)
+
+Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+
+## Release-Gate Determinism & Agents Vendor (v0.1.44)
+
+Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
+
+## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
+
+Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+0.1.51
+
+0.1.76
+
+0.1.77
+
+0.1.78

package/docs/operator-ux.7.md

@@ -0,0 +1,180 @@
+# Operator UX
+
+Cool Workflow v0.1.12 added a read-only Operator UX layer for understanding a
+run from the console. It does not change workflow state, dispatch workers, score
+candidates, or commit snapshots. It reads `WorkflowRun` state and renders
+deterministic summaries for humans while preserving JSON for scripts and MCP.
+
+## Inspect A Run
+
+Human status is the default:
+
+```bash
+node scripts/cw.js status <run-id>
+```
+
+The status view includes run id, workflow/app id and version, loop stage, active
+phase, blocked reasons, phase/task counts, workers, candidates, feedback,
+commits, multi-agent runtime health, Multi-Agent Operator UX counts, report
+path, and the next recommended command.
+
+Machine-readable status stays available:
+
+```bash
+node scripts/cw.js status <run-id> --json
+node scripts/cw.js status <run-id> --format json
+```
+
+`CoolWorkflowRunner.status()` and MCP `cw_status` continue to return structured
+status data for integrations.
+
+In v0.1.13, MCP also exposes JSON-native operator tools:
+`cw_operator_status`, `cw_operator_graph`, `cw_operator_report`,
+`cw_worker_summary`, `cw_candidate_summary`, `cw_feedback_summary`, and
+`cw_commit_summary`.
+
+## Next Actions
+
+Recommendations are deterministic and only use commands that exist in the CW
+CLI. Examples:
+
+```text
+node scripts/cw.js dispatch <run-id> --limit 4
+  reason: pending tasks are ready for the active phase
+
+node scripts/cw.js worker manifest <run-id> <worker-id>
+  reason: running workers need their manifests inspected
+
+node scripts/cw.js feedback show <run-id> <feedback-id>
+  reason: open feedback should be resolved before more dispatch
+
+node scripts/cw.js candidate register <run-id> --worker <worker-id>
+  reason: a completed worker result has not been registered as a candidate
+
+node scripts/cw.js commit <run-id> --selection <selection-id>
+  reason: a verified selected candidate is ready for a verifier-gated commit
+```
+
+Open feedback is prioritized before dispatch or candidate work. If all tracked
+work is complete, the advisor points to `cw report <run-id> --show`.
+
+## Graph
+
+Use the top-level graph command for a compact console map:
+
+```bash
+node scripts/cw.js graph <run-id>
+node scripts/cw.js graph <run-id> --json
+```
+
+The legacy node command remains compatible:
+
+```bash
+node scripts/cw.js node graph <run-id>
+node scripts/cw.js node graph <run-id> --json
+```
+
+The human graph groups phases, tasks, dispatches, workers, result nodes,
+verifier nodes, candidates, selections, commits, and feedback, then prints the
+edges between them. v0.1.17 also adds `multi-agent-run`, `agent-role`,
+`agent-group`, `agent-membership`, `agent-fanout`, and `agent-fanin` nodes when
+the run has first-class multi-agent state. v0.1.18 adds `blackboard`,
+`blackboard-topic`, `blackboard-message`, `blackboard-context`,
+`blackboard-artifact`, `blackboard-snapshot`, and `coordinator-decision` nodes
+when shared coordination state exists. JSON output returns deterministic `nodes`
+and `edges`.
+
+## Multi-Agent Operator UX
+
+v0.1.21 adds focused multi-agent operator views that answer who depends on
+whom, who is blocked, and which evidence was adopted into the accepted result:
+
+```bash
+node scripts/cw.js multi-agent graph <run-id>
+node scripts/cw.js multi-agent dependencies <run-id>
+node scripts/cw.js multi-agent failures <run-id>
+node scripts/cw.js multi-agent evidence <run-id>
+```
+
+The same derived model appears in `status`, `report --show`, and
+`cw_multi_agent_status` under `summaries.multiAgentOperator`. See
+[multi-agent-operator-ux.7.md](multi-agent-operator-ux.7.md) for the full
+trace from agent membership to verifier-gated commit.
+
+## Console Report
+
+`cw report` still writes the Markdown report file and prints its path:
+
+```bash
+node scripts/cw.js report <run-id>
+```
+
+Use `--show` or `--summary` when the operator needs a readable console report:
+
+```bash
+node scripts/cw.js report <run-id> --show
+node scripts/cw.js report <run-id> --summary
+```
+
+The console report includes the same high-value status panels plus active and
+pending tasks, evidence paths and locators, and resource inspection commands.
+
+## Resource Summaries
+
+Major run resources have human summaries by default and JSON when requested:
+
+```bash
+node scripts/cw.js worker summary <run-id>
+node scripts/cw.js worker summary <run-id> --json
+
+node scripts/cw.js candidate summary <run-id>
+node scripts/cw.js candidate summary <run-id> --json
+
+node scripts/cw.js feedback summary <run-id>
+node scripts/cw.js feedback summary <run-id> --json
+
+node scripts/cw.js commit summary <run-id>
+node scripts/cw.js commit summary <run-id> --json
+
+node scripts/cw.js multi-agent summary <run-id>
+node scripts/cw.js multi-agent summary <run-id> --json
+node scripts/cw.js multi-agent graph <run-id>
+node scripts/cw.js multi-agent graph <run-id> --json
+node scripts/cw.js multi-agent dependencies <run-id>
+node scripts/cw.js multi-agent failures <run-id>
+node scripts/cw.js multi-agent evidence <run-id>
+```
+
+Worker summaries show allocated/running/verified/failed/rejected counts,
+sandbox profile ids, manifest paths, result paths, and linked feedback for
+failed or rejected workers.
+
+Candidate summaries show registered/scored/selected/verified/rejected/failed
+counts, latest ranking path, selected candidates, candidates ready for commit,
+and obvious missing scoring/evidence/gate problems.
+
+Feedback summaries group records by open/tasked/resolved/rejected status,
+severity, classification, and retryability.
+
+Commit summaries distinguish verifier-gated commits from non-gated checkpoints
+and show snapshot paths, evidence counts, and linked verifier/candidate/selection
+ids.
+
+Multi-agent summaries show run and group status, role coverage, membership
+health, fanout/fanin progress, missing evidence, blocked reasons, and the next
+recommended action.
+
+## File Discipline
+
+Operator UX follows the same FreeBSD-flavored rule as the rest of CW:
+
+```text
+clear console output for humans
+stable JSON for scripts
+plain files for evidence
+no hidden daemon assumption
+```
+
+When in doubt, inspect `.cw/runs/<run-id>/state.json`, the resource directories,
+and the command-specific `--json` output.
+0.1.51