@twinsearth/w2m-dsh-plugin 1.9.10 → 1.9.11

package/src/relay/report.mjs

@@ -1,649 +1,651 @@
-/**
- * W2M Rabbit relay — §6.3 six-state aggregation + markdown/JSON reports.
- *
- * The step order is part of the contract: Step 0 → Step 1 → Step 2 → Step 3.
- * Steps are NEVER merged, because the order changes the verdict.
- */
-
-import {
-  COMPARABLE_FIELDS,
-  FAILURE_STATUSES,
-  ProtocolError,
-  PROTOCOL_VERSION,
-  jcs,
-  rfc3339,
-} from './state.mjs';
-
-/** Aggregate statuses this module can return. */
-export const AGGREGATE_STATUSES = Object.freeze([
-  // ---- the six verdicts of §6.3 ----
-  'consistent',
-  'divergent',
-  'divergent-platform',
-  'failed',
-  'partial',
-  'unverifiable',
-  // ---- added in v0.3.0 ----
-  //
-  // These three are *verdicts*, not phase flags, which is why they belong in this list rather than
-  // beside `pending`. Each answers a question the original six could not express:
-  //
-  //   timeout    nobody reported and the work is no longer waiting on anybody. `partial` said "some
-  //              machines are still out"; `timeout` says "we waited as long as we agreed to wait,
-  //              and the machines that never answered are not coming back".
-  //   cancelled  the operator stopped it. Distinct from `failed`: nothing went wrong, we chose this.
-  //              A cancellation must not be reported as a defect, or every intentional stop becomes
-  //              noise that trains people to ignore the status.
-  //   degraded   every machine reported, some succeeded and some failed. `partial` used to carry
-  //              this, but `partial` also means "still in flight", so a reader could not tell a
-  //              finished task in a bad state from one that had not finished. Both are now explicit.
-  'timeout',
-  'cancelled',
-  'degraded',
-  // ---- not verdicts: no terminal answer exists yet, or none was ever possible ----
-  'refused',
-  'pending',
-]);
-
-/** Comparable fields that are derived purely from the stdout byte stream. */
-const STDOUT_DERIVED_FIELDS = Object.freeze([
-  'stdout_sha256',
-  'stdout_bytes',
-  'stdout_normalized_sha256',
-]);
-
-function valueOf(envelope, field) {
-  return envelope === null || envelope === undefined ? undefined : envelope[field];
-}
-
-function canon(value) {
-  return value === undefined ? '<absent>' : jcs(value);
-}
-
-function truncate(text, max = 160) {
-  const s = typeof text === 'string' ? text : String(text);
-  return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
-}
-
-/**
- * Warning codes that explain *why* a machine failed, in a sentence a reader can act on.
- *
- * The envelope already carried these codes; nothing downstream read them. A spawn failure was
- * therefore rendered as `status: crashed`, `exit_code: null`, and an empty 说明 column -- the three
- * facts that together say nothing. Measured on macOS: a task whose `argv[0]` was not on PATH came
- * back exactly that way, with `warnings: ["PATH_INVALID"]` sitting unread in the envelope.
- *
- * Only codes whose meaning is unambiguous belong here. Inventing prose for a code we do not
- * understand would be worse than the empty cell, so anything unlisted stays unreported.
- */
-const FAILURE_WARNING_REASONS = {
-  PATH_INVALID: 'the command could not be started: an executable in the argv was not found (PATH_INVALID)',
-};
-
-/**
- * Fill in a failed machine's `reasons` from its execution warnings.
- *
- * `reasons` is what the human report renders in the 说明 column, and it was only ever populated by
- * anchor/comparison problems -- so a machine that never started had nothing to say for itself.
- *
- * @param {object} m Machine record being aggregated.
- * @param {string} status The envelope's execution status.
- */
-function explainExecutionFailure(m, status) {
-  if (m.reasons.length > 0) return;
-  // `nonzero_exit` is self-explanatory: the command ran and `exit_code` reports what it returned.
-  // Only a machine that produced no exit status at all needs the warning spelled out.
-  if (status !== 'crashed' && status !== 'timeout') return;
-  const warnings = Array.isArray(m.envelope?.warnings) ? m.envelope.warnings : [];
-  for (const warning of warnings) {
-    const reason = FAILURE_WARNING_REASONS[warning];
-    if (reason) {
-      m.reasons.push(reason);
-      return;
-    }
-  }
-}
-
-/**
- * §6.3 six-state aggregation.
- *
- * @param {object} task            Rabbit task record (state.mjs `createTask` result)
- * @param {Iterable<object>} resultRecords  result records from `RabbitState#results`
- * @param {{nowMs?:number}} [opts]
- * @returns {object} aggregation report data
- */
-export function aggregate(task, resultRecords = [], opts = {}) {
-  if (!task) throw new ProtocolError('NOT_FOUND', 'task is required for aggregation');
-  const nowMs = opts.nowMs ?? Date.now();
-
-  const records = [...resultRecords].filter((r) => r?.envelope?.task_id === task.task_id);
-  // latest attempt per machine wins
-  const byMachine = new Map();
-  for (const rec of records) {
-    const prev = byMachine.get(rec.machine_id);
-    if (!prev || rec.received_at_ms >= prev.received_at_ms) byMachine.set(rec.machine_id, rec);
-  }
-
-  const expected = {
-    base_commit: task.base_commit ?? null,
-    base_tree: task.base_tree ?? null,
-    command_hash: task.command_hash ?? null,
-  };
-
-  const machines = [];
-  for (const lease of task.leases.values()) {
-    const rec = byMachine.get(lease.machine_id) ?? null;
-    machines.push({
-      machine_id: lease.machine_id,
-      machine_name: lease.machine_name ?? null,
-      index: lease.index,
-      attempt: lease.attempt,
-      lease_state: lease.state,
-      lease_expired: lease.state === 'expired',
-      refused_reason: lease.refusal_reason ?? null,
-      gate_refused: lease.state === 'refused',
-      // v0.3.3 `broadcast`: a machine that was told the outcome but never handed the command. It has
-      // no envelope and never will, so without this marker the anchor step classified it `pending`
-      // and the task could never reach a verdict -- a broadcast would hang forever.
-      observing: lease.state === 'observing',
-      result: rec,
-      envelope: rec?.envelope ?? null,
-      // v1.2.6: the relay's own signature verdict (bound to the key registered at pairing), not a client claim.
-      signature_status: rec?.validation?.signature_status ?? null,
-      outcome: null,
-      reasons: [],
-    });
-  }
-  // results from machines with no lease (e.g. takeover / manual upload)
-  for (const [machineId, rec] of byMachine) {
-    if (machines.some((m) => m.machine_id === machineId)) continue;
-    machines.push({
-      machine_id: machineId,
-      machine_name: rec.envelope.machine_name ?? null,
-      index: rec.envelope.index ?? null,
-      attempt: rec.attempt,
-      lease_state: 'unleased',
-      lease_expired: false,
-      refused_reason: rec.envelope.refusal_reason ?? null,
-      gate_refused: false,
-      result: rec,
-      envelope: rec.envelope,
-      signature_status: rec?.validation?.signature_status ?? null,
-      outcome: null,
-      reasons: [],
-    });
-  }
-
-  const steps = [];
-  const notes = [];
-
-  /* -------- Step 0: refusals are booked per machine, they never block others -------- */
-  const step0 = { step: 0, name: 'refusal', refused: [], passed: [], observing: [] };
-  for (const m of machines) {
-    if (m.observing) {
-      // Not a participant: it was never asked to run, so it cannot refuse, cannot pass, and must
-      // never be counted as agreeing. Recording the outcome is the whole reason it is listed.
-      m.outcome = 'observing';
-      step0.observing.push(m.machine_id);
-      continue;
-    }
-    const refusedByGate = m.gate_refused;
-    const refusedByEnvelope = m.envelope?.status === 'refused';
-    if (refusedByGate || refusedByEnvelope) {
-      m.outcome = 'refused';
-      m.refusal_reason = refusedByGate
-        ? (m.refused_reason ?? 'REFUSED')
-        : (m.envelope.refusal_reason ?? 'REFUSED');
-      step0.refused.push({ machine_id: m.machine_id, refusal_reason: m.refusal_reason });
-    } else {
-      step0.passed.push(m.machine_id);
-    }
-  }
-  steps.push(step0);
-
-  const participants = machines.filter((m) => m.outcome !== 'refused' && m.outcome !== 'observing');
-
-  /* -------- Step 1: anchors — any violation refuses aggregation entirely -------- */
-  const step1 = { step: 1, name: 'anchors', violations: [], passed: [], pending: [] };
-  for (const m of participants) {
-    const env = m.envelope;
-    if (!env) {
-      const expired = m.lease_expired;
-      m.outcome = expired ? 'expired' : 'pending';
-      step1.pending.push(m.machine_id);
-      continue;
-    }
-    const validation = m.result?.validation ?? { missing: [], problems: [] };
-    const missing = [...(validation.missing ?? [])];
-    if (m.result?.effective_status === 'unverifiable' && missing.length === 0) {
-      m.reasons.push('envelope status = unverifiable');
-    }
-    if (missing.length > 0) m.reasons.push(`missing required fields: ${missing.join(',')}`);
-    /**
-     * v0.9.3: `base_commit` is enforced only when the dispatcher declared one.
-     *
-     * The check used to be unconditional, so a dispatcher with **no** anchor -- one whose own tree is
-     * not a git work tree, which is the ordinary case for a machine that runs the plugin from its
-     * profile directory -- sent `base_commit: null`, and every result was then compared against the
-     * literal `null`. Any machine that *did* have an anchor reported its real commit and was marked
-     * `unverifiable` for telling the truth:
-     *
-     *     expected.base_commit : null
-     *     machine reported     : a1e7dc042913b96da3ad68…
-     *     reasons              : ["base_commit \"a1e7dc04…\" != expected null"]
-     *     notes                : ["aggregation refused: Step 1 anchor violation"]
-     *
-     * which downgraded **every** dispatch from such a machine, including a wholly successful one, and
-     * made the verdict unreadable. The anchor exists to answer "did these machines run the same tree";
-     * with nothing declared there is no such question, and the honest verdict is that the run is
-     * unanchored -- not that it disagreed with `null`.
-     *
-     * `base_tree` three lines below has always read this way (`expected.base_tree !== null && …`), and
-     * the asymmetry was the bug: the two anchors are the same kind of statement and one of them
-     * tolerated absence while the other did not.
-     *
-     * An absent anchor is still *reported* rather than silently ignored -- `unanchored: true` on the
-     * aggregate and in the machine's own record -- because "these two machines agreed" and "nobody
-     * said what they should have agreed on" must not read the same to an operator.
-     */
-    if (expected.base_commit !== null && canon(valueOf(env, 'base_commit')) !== canon(expected.base_commit)) {
-      m.reasons.push(`base_commit ${truncate(canon(env.base_commit), 24)} != expected ${truncate(canon(expected.base_commit), 24)}`);
-    }
-    if (expected.base_tree !== null && canon(valueOf(env, 'pre_tree_fingerprint')) !== canon(expected.base_tree)) {
-      m.reasons.push('pre_tree_fingerprint != base_tree');
-    }
-    if (canon(valueOf(env, 'command_hash')) !== canon(expected.command_hash)) {
-      m.reasons.push('command_hash mismatch');
-    }
-    if (env.status === 'unverifiable' && m.reasons.length === 0) {
-      m.reasons.push('envelope status = unverifiable');
-    }
-    if (m.reasons.length > 0) {
-      m.outcome = 'unverifiable';
-      step1.violations.push({ machine_id: m.machine_id, reasons: [...m.reasons] });
-    } else {
-      m.outcome = 'ok-pending-step2';
-      step1.passed.push(m.machine_id);
-    }
-  }
-  steps.push(step1);
-
-  const runnable = participants.filter((m) => m.outcome === 'ok-pending-step2');
-  const expiredMachines = participants.filter((m) => m.outcome === 'expired');
-  const pendingMachines = participants.filter((m) => m.outcome === 'pending');
-
-  let status;
-  const step2 = { step: 2, name: 'execution', ok: [], failed: [], partial: false, expired: [], pending: [] };
-  const step3 = { step: 3, name: 'comparison', differences: [], consistent: false, platform_only: false };
-
-  if (step1.violations.length > 0) {
-    /* §6.3 Step 1: 拒绝汇总 */
-    status = 'unverifiable';
-    step2.skipped = 'step1_unverifiable';
-    step3.skipped = 'step1_unverifiable';
-    notes.push('aggregation refused: Step 1 anchor violation (see unverifiable machines)');
-  } else if (task.cancelled === true) {
-    /* v0.3.0: the operator stopped it. A chosen stop is not a defect. */
-    //
-    // Checked before `unverifiable`-adjacent outcomes and before any timeout: once someone has
-    // deliberately stopped the work, reporting "failed" or "timed out" would describe a decision as
-    // a malfunction, and enough of those trains a reader to ignore the status entirely.
-    status = 'cancelled';
-    step2.skipped = 'task_cancelled';
-    step3.skipped = 'task_cancelled';
-    notes.push(
-      task.cancel_reason ? `cancelled by the operator: ${task.cancel_reason}` : 'cancelled by the operator',
-    );
-  } else if (runnable.length === 0 && expiredMachines.length === 0 && pendingMachines.length === 0 && step0.refused.length > 0) {
-    status = 'refused';
-    step2.skipped = 'all_refused';
-    step3.skipped = 'all_refused';
-  } else if (runnable.length === 0 && expiredMachines.length === 0) {
-    /* v0.3.0: distinguish "still waiting" from "waited long enough". */
-    //
-    // `pending` means the task is live and more envelopes may still arrive. Once the deadline the
-    // caller set has passed and machines are still silent, that is a verdict, and calling it
-    // `pending` forever leaves a reader unable to tell a stuck task from a slow one.
-    const deadline = Number.isFinite(task.deadline_ms) ? task.deadline_ms : 0;
-    if (deadline > 0 && nowMs >= deadline) {
-      status = 'timeout';
-      step2.skipped = 'deadline_passed';
-      step3.skipped = 'deadline_passed';
-      notes.push(
-        `no result envelope by the ${task.timeout_ms}ms deadline (${pendingMachines.length} machine(s) still silent)`,
-      );
-    } else {
-      status = 'pending';
-      step2.skipped = 'no_results_yet';
-      step3.skipped = 'no_results_yet';
-      notes.push('no result envelope has been received yet');
-    }
-  } else {
-    for (const m of runnable) {
-      const s = m.envelope.status;
-      if (s === 'ok') { m.outcome = 'ok'; step2.ok.push(m.machine_id); }
-      else {
-        // {nonzero_exit,timeout,crashed} plus anything outside the §5.1 enum
-        m.outcome = 'failed';
-        explainExecutionFailure(m, s);
-        step2.failed.push({
-          machine_id: m.machine_id,
-          status: s,
-          exit_code: m.envelope.exit_code ?? null,
-          known_failure: FAILURE_STATUSES.includes(s),
-        });
-      }
-    }
-    for (const m of expiredMachines) step2.expired.push(m.machine_id);
-    for (const m of pendingMachines) step2.pending.push(m.machine_id);
-
-    if (step2.expired.length > 0) {
-      /* §4.3: halt=never → booked and marked partial */
-      status = 'partial';
-      step2.partial = true;
-      notes.push(`lease expired on ${step2.expired.length} machine(s) → partial (§4.3)`);
-      step3.skipped = 'lease_expired';
-    } else if (step2.pending.length > 0) {
-      status = 'partial';
-      step2.partial = true;
-      notes.push(`waiting for ${step2.pending.length} machine(s) to report`);
-      step3.skipped = 'machines_pending';
-    } else if (step2.failed.length === 0 && step2.ok.length > 0) {
-      /* §6.3 Step 2: 全部 ok → Step 3 */
-      const okMachines = runnable.filter((m) => m.outcome === 'ok');
-
-      // Compare **within a shard**, not across the whole task.
-      //
-      // `index` is a comparable field, and `split` assigns it per machine by design -- so comparing
-      // every machine against every other made `index` differ on any successful fan-out, and every
-      // split task was reported `divergent`. That is a false alarm on the normal case: `divergent`
-      // tells an operator the machines disagreed, when in fact they did exactly what was asked.
-      //
-      // Grouping by `index` fixes it without special-casing the field: machines meant to produce the
-      // same output are compared with each other, and machines given different slices are not
-      // compared at all. For `replicate` every machine has index 0, so there is a single group and
-      // the behaviour is exactly as before -- which is why the existing 140 relay tests still pass
-      // unchanged.
-      const shards = new Map();
-      for (const m of okMachines) {
-        const key = m.index ?? 0;
-        if (!shards.has(key)) shards.set(key, []);
-        shards.get(key).push(m);
-      }
-
-      const comparable = {};
-      for (const field of COMPARABLE_FIELDS) {
-        comparable[field] = {};
-        for (const m of okMachines) {
-          const v = valueOf(m.envelope, field);
-          if (v !== undefined) comparable[field][m.machine_id] = v;
-        }
-      }
-
-      /**
-       * Fields that differ within some shard, with the shard that disagreed.
-       *
-       * `index` is reported with the shard so a genuine mixed-mode divergence ("shard 0 agreed,
-       * shard 1 did not") stays unambiguous.
-       */
-      const differences = [];
-      for (const [shardIndex, members] of shards) {
-        if (members.length < 2) continue; // one machine cannot disagree with itself
-        for (const field of COMPARABLE_FIELDS) {
-          const values = members.map((m) => canon(valueOf(m.envelope, field)));
-          if (values.some((v) => v !== values[0])) {
-            differences.push({
-              field,
-              index: shardIndex,
-              values: Object.fromEntries(members.map((m) => [m.machine_id, valueOf(m.envelope, field)])),
-            });
-          }
-        }
-      }
-      step3.comparable = comparable;
-      step3.differences = differences;
-
-      /** Metadata drift within any shard, for the `divergent-platform` branch. */
-      const metaDiffers = (field) => {
-        for (const members of shards.values()) {
-          if (members.length < 2) continue;
-          const vals = members.map((m) => canon(valueOf(m.envelope, field)));
-          if (vals.some((v) => v !== vals[0])) return true;
-        }
-        return false;
-      };
-      const platformMetaDiffers = metaDiffers('toolchain') || metaDiffers('platform');
-
-      if (differences.length === 0) {
-        status = 'consistent';
-        step3.consistent = true;
-      } else if (platformMetaDiffers && differences.every((d) => STDOUT_DERIVED_FIELDS.includes(d.field))) {
-        /* §6.3 Step 3: expected — only toolchain/platform differ and the drift is stdout-only */
-        status = 'divergent-platform';
-        step3.platform_only = true;
-        notes.push('divergence is confined to stdout bytes across differing toolchain/platform (expected, no alert)');
-      } else {
-        status = 'divergent';
-        notes.push(`divergent fields: ${differences.map((d) => d.field).join(', ')}`);
-      }
-    } else if (step2.ok.length > 0) {
-      /* v0.3.0 §6.3 Step 2: 部分 ok、部分失败 → degraded */
-      //
-      // This used to be `partial`, which was wrong in a way that mattered: `partial` is also the
-      // answer while machines are still out, so "finished, and half of it failed" was
-      // indistinguishable from "still running" in the one field a reader looks at first. Every
-      // machine here has reported, so the task is over and the verdict is `degraded` -- some of the
-      // work succeeded, the rest did not, and nothing further is coming.
-      status = 'degraded';
-      step2.partial = true;
-      notes.push(`${step2.ok.length} machine(s) succeeded and ${step2.failed.length} failed`);
-    } else {
-      /* §6.3 Step 2: 全部失败 → failed */
-      status = 'failed';
-    }
-  }
-
-  steps.push(step2);
-  steps.push(step3);
-
-  return {
-    protocol_version: PROTOCOL_VERSION,
-    task_id: task.task_id,
-    status,
-    computed_at: rfc3339(nowMs),
-    mode: task.mode,
-    index_total: task.index_total,
-    halt: task.halt,
-    write: task.write,
-    created_at: rfc3339(task.created_at_ms),
-    created_by: task.created_by ?? null,
-    cancelled: task.cancelled === true,
-    expected,
-    /**
-     * v0.9.3: whether this task ran against a declared tree at all.
-     *
-     * `expected.base_commit === null` means the dispatcher declared no anchor -- its own tree is not a
-     * git work tree, which is the ordinary case for the plugin running out of a profile directory. The
-     * anchor check is therefore skipped rather than compared against the literal `null` (see Step 1).
-     *
-     * Reported explicitly because the two situations must not look alike: `consistent: true` from an
-     * unanchored run says "these machines agreed with each other", **not** "these machines ran the
-     * tree you meant". An operator comparing results needs to know which of those they are holding.
-     */
-    unanchored: expected.base_commit === null,
-    machines: machines.map((m) => ({
-      machine_id: m.machine_id,
-      machine_name: m.machine_name,
-      index: m.index,
-      attempt: m.attempt,
-      lease_state: m.lease_state,
-      outcome: m.outcome,
-      status: m.envelope?.status ?? null,
-      refusal_reason: m.refusal_reason ?? null,
-      exit_code: m.envelope?.exit_code ?? null,
-      /* v0.4.0: how this machine's envelope travelled, straight off the stored envelope.
-       *
-       * `null` means "the envelope did not say" -- every v0.3.9 result, and the honest answer for a
-       * relay that simply does not know. These two fields are REPORTED, never judged: they are not
-       * in COMPARABLE_FIELDS, so a machine that answered over P2P and one that answered over the
-       * relay still produce the same verdict. A path is not a result. */
-      transport: m.envelope?.transport ?? null,
-      p2p: m.envelope?.p2p ?? null,
-      reasons: m.reasons,
-      // v1.2.6: the relay's verdict, bound to the key registered at pairing.
-      signature_status: m.signature_status ?? null,
-      /**
-       * v1.2.7: the dataflow facts a reader needs to build a reduce plan.
-       *
-       * The aggregate used to publish only a summary per machine, so a client could not see that a result was a blob -- the
-       * reduce plan existed in tests and read raw envelopes that the production response never carried. These four fields are
-       * that omission, closed: the blob hash, the file/blob mode, the inline head, and the byte count.
-       */
-      blob_sha256: m.envelope?.blob_sha256 ?? null,
-      output_mode: m.envelope?.output_mode ?? null,
-      stdout_head: m.envelope?.stdout_head ?? null,
-      stdout_bytes: m.envelope?.stdout_bytes ?? null,
-    })),
-    steps,
-    differences: step3.differences ?? [],
-    notes: expected.base_commit === null
-      ? [...notes, 'no base_commit was declared, so the anchor check did not run: machine agreement here is '
-        + 'agreement with each other, not with a tree the dispatcher named']
-      : notes,
-    counts: {
-      refused: step0.refused.length,
-      unverifiable: step1.violations.length,
-      ok: step2.ok?.length ?? 0,
-      failed: step2.failed?.length ?? 0,
-      expired: step2.expired?.length ?? 0,
-      pending: step2.pending?.length ?? 0,
-    },
-  };
-}
-
-/** Convenience wrapper: pull the task + its results out of a RabbitState. */
-export function aggregateTask(state, taskId, opts = {}) {
-  const task = state.getTask(taskId);
-  if (!task) throw new ProtocolError('NOT_FOUND', 'unknown task_id', { task_id: taskId });
-  return aggregate(task, state.results.values(), opts);
-}
-
-const STATUS_LABEL = Object.freeze({
-  consistent: '✅ consistent',
-  divergent: '❌ divergent',
-  'divergent-platform': '🟡 divergent-platform',
-  failed: '❌ failed',
-  partial: '🟠 partial',
-  unverifiable: '⚠️ unverifiable',
-  // v0.3.0 verdicts. Each keeps a distinct shape because these are read at a glance: `partial`
-  // (still out), `degraded` (finished badly) and `timeout` (never answered) must not look alike.
-  degraded: '🟧 degraded',
-  timeout: '⏱️ timeout',
-  cancelled: '🚫 cancelled',
-  refused: '⛔ refused',
-  pending: '⏳ pending',
-});
-
-function fmt(value) {
-  if (value === undefined) return '—';
-  if (value === null) return 'null';
-  if (typeof value === 'string') return value.length > 80 ? `${value.slice(0, 79)}…` : value;
-  return truncate(jcs(value), 80);
-}
-
-/** Markdown summary report (GET /v1/tasks/{id}/report?format=md). */
-export function renderReportMarkdown(agg, task = null) {
-  const L = [];
-  L.push(`# W2M 汇总报告 — \`${agg.task_id}\``);
-  L.push('');
-  L.push(`**判定：${STATUS_LABEL[agg.status] ?? agg.status}**`);
-  L.push('');
-  L.push('| 字段 | 值 |');
-  L.push('|---|---|');
-  L.push(`| protocol_version | ${agg.protocol_version} |`);
-  L.push(`| 模式 | ${agg.mode} |`);
-  L.push(`| index_total | ${agg.index_total} |`);
-  L.push(`| 写入 | ${agg.write} |`);
-  L.push(`| halt | ${agg.halt} |`);
-  L.push(`| 创建者 | ${fmt(agg.created_by)} |`);
-  L.push(`| 创建时间 | ${agg.created_at} |`);
-  L.push(`| 汇总时间 | ${agg.computed_at} |`);
-  L.push(`| base_commit | \`${fmt(agg.expected.base_commit)}\` |`);
-  L.push(`| base_tree | \`${fmt(agg.expected.base_tree)}\` |`);
-  L.push(`| command_hash | \`${fmt(agg.expected.command_hash)}\` |`);
-  L.push('');
-  L.push('## 逐机结果');
-  L.push('');
-  L.push('| machine_id | index | lease | 判定 | status | exit_code | 说明 | 路径 |');
-  L.push('|---|---|---|---|---|---|---|---|');
-  for (const m of agg.machines) {
-    // v0.4.0: the trailing 路径 column is APPENDED, so every existing column keeps its name and
-    // position and a reader written against v0.3.9 output is unaffected. `-` is "the envelope did
-    // not say" (every v0.3.9 result), which is not the same claim as `relay`.
-    L.push(`| \`${m.machine_id}\` | ${fmt(m.index)} | ${m.lease_state} | ${m.outcome ?? '—'} | ${fmt(m.status)} `
-      + `| ${fmt(m.exit_code)} | ${m.reasons.length ? m.reasons.join('; ') : (m.refusal_reason ?? '')} `
-      + `| ${m.transport ?? '-'} |`);
-  }
-  L.push('');
-  if (agg.differences.length > 0) {
-    L.push('## 可比字段差异');
-    L.push('');
-    for (const d of agg.differences) {
-      L.push(`### \`${d.field}\``);
-      L.push('');
-      L.push('| machine_id | value |');
-      L.push('|---|---|');
-      for (const [machine, value] of Object.entries(d.values)) {
-        L.push(`| \`${machine}\` | \`${fmt(value)}\` |`);
-      }
-      L.push('');
-    }
-  }
-  L.push('## 判定步骤（§6.3，顺序不可合并）');
-  L.push('');
-  for (const s of agg.steps) {
-    L.push(`- **Step ${s.step} · ${s.name}** — ${truncate(jcs(s), 400)}`);
-  }
-  L.push('');
-  if (agg.notes.length > 0) {
-    L.push('## 备注');
-    L.push('');
-    for (const n of agg.notes) L.push(`- ${n}`);
-    L.push('');
-  }
-  if (task) {
-    L.push('## 原始命令');
-    L.push('');
-    L.push('```');
-    L.push(jcs(task.command_argv));
-    L.push('```');
-    L.push('');
-  }
-  return L.join('\n');
-}
-
-/** JSON report (GET /v1/tasks/{id}/report?format=json). */
-export function renderReportJson(agg) {
-  return JSON.stringify(agg, null, 2);
-}
-
-/**
- * Build a report of the requested format.
- * @returns {{contentType:string, body:string, aggregate:object}}
- */
-export function buildReport(state, taskId, { format = 'json', nowMs } = {}) {
-  const agg = aggregateTask(state, taskId, { nowMs });
-  const task = state.getTask(taskId);
-  if (format === 'md' || format === 'markdown') {
-    return { contentType: 'text/markdown; charset=utf-8', body: renderReportMarkdown(agg, task), aggregate: agg };
-  }
-  if (format === 'json') {
-    return { contentType: 'application/json; charset=utf-8', body: renderReportJson(agg), aggregate: agg };
-  }
-  throw new ProtocolError('BAD_REQUEST', 'format must be md|json', { format });
-}
-
-/** Machine-readable verdict used by GET /v1/tasks/{id}. */
-export function taskStatus(state, taskId, opts = {}) {
-  return aggregateTask(state, taskId, opts);
-}
+/**
+ * W2M Rabbit relay — §6.3 six-state aggregation + markdown/JSON reports.
+ *
+ * The step order is part of the contract: Step 0 → Step 1 → Step 2 → Step 3.
+ * Steps are NEVER merged, because the order changes the verdict.
+ */
+
+import {
+  COMPARABLE_FIELDS,
+  FAILURE_STATUSES,
+  ProtocolError,
+  PROTOCOL_VERSION,
+  jcs,
+  rfc3339,
+} from './state.mjs';
+
+import { stripReportAggregate } from './p0-projection.mjs';
+
+/** Aggregate statuses this module can return. */
+export const AGGREGATE_STATUSES = Object.freeze([
+  // ---- the six verdicts of §6.3 ----
+  'consistent',
+  'divergent',
+  'divergent-platform',
+  'failed',
+  'partial',
+  'unverifiable',
+  // ---- added in v0.3.0 ----
+  //
+  // These three are *verdicts*, not phase flags, which is why they belong in this list rather than
+  // beside `pending`. Each answers a question the original six could not express:
+  //
+  //   timeout    nobody reported and the work is no longer waiting on anybody. `partial` said "some
+  //              machines are still out"; `timeout` says "we waited as long as we agreed to wait,
+  //              and the machines that never answered are not coming back".
+  //   cancelled  the operator stopped it. Distinct from `failed`: nothing went wrong, we chose this.
+  //              A cancellation must not be reported as a defect, or every intentional stop becomes
+  //              noise that trains people to ignore the status.
+  //   degraded   every machine reported, some succeeded and some failed. `partial` used to carry
+  //              this, but `partial` also means "still in flight", so a reader could not tell a
+  //              finished task in a bad state from one that had not finished. Both are now explicit.
+  'timeout',
+  'cancelled',
+  'degraded',
+  // ---- not verdicts: no terminal answer exists yet, or none was ever possible ----
+  'refused',
+  'pending',
+]);
+
+/** Comparable fields that are derived purely from the stdout byte stream. */
+const STDOUT_DERIVED_FIELDS = Object.freeze([
+  'stdout_sha256',
+  'stdout_bytes',
+  'stdout_normalized_sha256',
+]);
+
+function valueOf(envelope, field) {
+  return envelope === null || envelope === undefined ? undefined : envelope[field];
+}
+
+function canon(value) {
+  return value === undefined ? '<absent>' : jcs(value);
+}
+
+function truncate(text, max = 160) {
+  const s = typeof text === 'string' ? text : String(text);
+  return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}
+
+/**
+ * Warning codes that explain *why* a machine failed, in a sentence a reader can act on.
+ *
+ * The envelope already carried these codes; nothing downstream read them. A spawn failure was
+ * therefore rendered as `status: crashed`, `exit_code: null`, and an empty 说明 column -- the three
+ * facts that together say nothing. Measured on macOS: a task whose `argv[0]` was not on PATH came
+ * back exactly that way, with `warnings: ["PATH_INVALID"]` sitting unread in the envelope.
+ *
+ * Only codes whose meaning is unambiguous belong here. Inventing prose for a code we do not
+ * understand would be worse than the empty cell, so anything unlisted stays unreported.
+ */
+const FAILURE_WARNING_REASONS = {
+  PATH_INVALID: 'the command could not be started: an executable in the argv was not found (PATH_INVALID)',
+};
+
+/**
+ * Fill in a failed machine's `reasons` from its execution warnings.
+ *
+ * `reasons` is what the human report renders in the 说明 column, and it was only ever populated by
+ * anchor/comparison problems -- so a machine that never started had nothing to say for itself.
+ *
+ * @param {object} m Machine record being aggregated.
+ * @param {string} status The envelope's execution status.
+ */
+function explainExecutionFailure(m, status) {
+  if (m.reasons.length > 0) return;
+  // `nonzero_exit` is self-explanatory: the command ran and `exit_code` reports what it returned.
+  // Only a machine that produced no exit status at all needs the warning spelled out.
+  if (status !== 'crashed' && status !== 'timeout') return;
+  const warnings = Array.isArray(m.envelope?.warnings) ? m.envelope.warnings : [];
+  for (const warning of warnings) {
+    const reason = FAILURE_WARNING_REASONS[warning];
+    if (reason) {
+      m.reasons.push(reason);
+      return;
+    }
+  }
+}
+
+/**
+ * §6.3 six-state aggregation.
+ *
+ * @param {object} task            Rabbit task record (state.mjs `createTask` result)
+ * @param {Iterable<object>} resultRecords  result records from `RabbitState#results`
+ * @param {{nowMs?:number}} [opts]
+ * @returns {object} aggregation report data
+ */
+export function aggregate(task, resultRecords = [], opts = {}) {
+  if (!task) throw new ProtocolError('NOT_FOUND', 'task is required for aggregation');
+  const nowMs = opts.nowMs ?? Date.now();
+
+  const records = [...resultRecords].filter((r) => r?.envelope?.task_id === task.task_id);
+  // latest attempt per machine wins
+  const byMachine = new Map();
+  for (const rec of records) {
+    const prev = byMachine.get(rec.machine_id);
+    if (!prev || rec.received_at_ms >= prev.received_at_ms) byMachine.set(rec.machine_id, rec);
+  }
+
+  const expected = {
+    base_commit: task.base_commit ?? null,
+    base_tree: task.base_tree ?? null,
+    command_hash: task.command_hash ?? null,
+  };
+
+  const machines = [];
+  for (const lease of task.leases.values()) {
+    const rec = byMachine.get(lease.machine_id) ?? null;
+    machines.push({
+      machine_id: lease.machine_id,
+      machine_name: lease.machine_name ?? null,
+      index: lease.index,
+      attempt: lease.attempt,
+      lease_state: lease.state,
+      lease_expired: lease.state === 'expired',
+      refused_reason: lease.refusal_reason ?? null,
+      gate_refused: lease.state === 'refused',
+      // v0.3.3 `broadcast`: a machine that was told the outcome but never handed the command. It has
+      // no envelope and never will, so without this marker the anchor step classified it `pending`
+      // and the task could never reach a verdict -- a broadcast would hang forever.
+      observing: lease.state === 'observing',
+      result: rec,
+      envelope: rec?.envelope ?? null,
+      // v1.2.6: the relay's own signature verdict (bound to the key registered at pairing), not a client claim.
+      signature_status: rec?.validation?.signature_status ?? null,
+      outcome: null,
+      reasons: [],
+    });
+  }
+  // results from machines with no lease (e.g. takeover / manual upload)
+  for (const [machineId, rec] of byMachine) {
+    if (machines.some((m) => m.machine_id === machineId)) continue;
+    machines.push({
+      machine_id: machineId,
+      machine_name: rec.envelope.machine_name ?? null,
+      index: rec.envelope.index ?? null,
+      attempt: rec.attempt,
+      lease_state: 'unleased',
+      lease_expired: false,
+      refused_reason: rec.envelope.refusal_reason ?? null,
+      gate_refused: false,
+      result: rec,
+      envelope: rec.envelope,
+      signature_status: rec?.validation?.signature_status ?? null,
+      outcome: null,
+      reasons: [],
+    });
+  }
+
+  const steps = [];
+  const notes = [];
+
+  /* -------- Step 0: refusals are booked per machine, they never block others -------- */
+  const step0 = { step: 0, name: 'refusal', refused: [], passed: [], observing: [] };
+  for (const m of machines) {
+    if (m.observing) {
+      // Not a participant: it was never asked to run, so it cannot refuse, cannot pass, and must
+      // never be counted as agreeing. Recording the outcome is the whole reason it is listed.
+      m.outcome = 'observing';
+      step0.observing.push(m.machine_id);
+      continue;
+    }
+    const refusedByGate = m.gate_refused;
+    const refusedByEnvelope = m.envelope?.status === 'refused';
+    if (refusedByGate || refusedByEnvelope) {
+      m.outcome = 'refused';
+      m.refusal_reason = refusedByGate
+        ? (m.refused_reason ?? 'REFUSED')
+        : (m.envelope.refusal_reason ?? 'REFUSED');
+      step0.refused.push({ machine_id: m.machine_id, refusal_reason: m.refusal_reason });
+    } else {
+      step0.passed.push(m.machine_id);
+    }
+  }
+  steps.push(step0);
+
+  const participants = machines.filter((m) => m.outcome !== 'refused' && m.outcome !== 'observing');
+
+  /* -------- Step 1: anchors — any violation refuses aggregation entirely -------- */
+  const step1 = { step: 1, name: 'anchors', violations: [], passed: [], pending: [] };
+  for (const m of participants) {
+    const env = m.envelope;
+    if (!env) {
+      const expired = m.lease_expired;
+      m.outcome = expired ? 'expired' : 'pending';
+      step1.pending.push(m.machine_id);
+      continue;
+    }
+    const validation = m.result?.validation ?? { missing: [], problems: [] };
+    const missing = [...(validation.missing ?? [])];
+    if (m.result?.effective_status === 'unverifiable' && missing.length === 0) {
+      m.reasons.push('envelope status = unverifiable');
+    }
+    if (missing.length > 0) m.reasons.push(`missing required fields: ${missing.join(',')}`);
+    /**
+     * v0.9.3: `base_commit` is enforced only when the dispatcher declared one.
+     *
+     * The check used to be unconditional, so a dispatcher with **no** anchor -- one whose own tree is
+     * not a git work tree, which is the ordinary case for a machine that runs the plugin from its
+     * profile directory -- sent `base_commit: null`, and every result was then compared against the
+     * literal `null`. Any machine that *did* have an anchor reported its real commit and was marked
+     * `unverifiable` for telling the truth:
+     *
+     *     expected.base_commit : null
+     *     machine reported     : a1e7dc042913b96da3ad68…
+     *     reasons              : ["base_commit \"a1e7dc04…\" != expected null"]
+     *     notes                : ["aggregation refused: Step 1 anchor violation"]
+     *
+     * which downgraded **every** dispatch from such a machine, including a wholly successful one, and
+     * made the verdict unreadable. The anchor exists to answer "did these machines run the same tree";
+     * with nothing declared there is no such question, and the honest verdict is that the run is
+     * unanchored -- not that it disagreed with `null`.
+     *
+     * `base_tree` three lines below has always read this way (`expected.base_tree !== null && …`), and
+     * the asymmetry was the bug: the two anchors are the same kind of statement and one of them
+     * tolerated absence while the other did not.
+     *
+     * An absent anchor is still *reported* rather than silently ignored -- `unanchored: true` on the
+     * aggregate and in the machine's own record -- because "these two machines agreed" and "nobody
+     * said what they should have agreed on" must not read the same to an operator.
+     */
+    if (expected.base_commit !== null && canon(valueOf(env, 'base_commit')) !== canon(expected.base_commit)) {
+      m.reasons.push(`base_commit ${truncate(canon(env.base_commit), 24)} != expected ${truncate(canon(expected.base_commit), 24)}`);
+    }
+    if (expected.base_tree !== null && canon(valueOf(env, 'pre_tree_fingerprint')) !== canon(expected.base_tree)) {
+      m.reasons.push('pre_tree_fingerprint != base_tree');
+    }
+    if (canon(valueOf(env, 'command_hash')) !== canon(expected.command_hash)) {
+      m.reasons.push('command_hash mismatch');
+    }
+    if (env.status === 'unverifiable' && m.reasons.length === 0) {
+      m.reasons.push('envelope status = unverifiable');
+    }
+    if (m.reasons.length > 0) {
+      m.outcome = 'unverifiable';
+      step1.violations.push({ machine_id: m.machine_id, reasons: [...m.reasons] });
+    } else {
+      m.outcome = 'ok-pending-step2';
+      step1.passed.push(m.machine_id);
+    }
+  }
+  steps.push(step1);
+
+  const runnable = participants.filter((m) => m.outcome === 'ok-pending-step2');
+  const expiredMachines = participants.filter((m) => m.outcome === 'expired');
+  const pendingMachines = participants.filter((m) => m.outcome === 'pending');
+
+  let status;
+  const step2 = { step: 2, name: 'execution', ok: [], failed: [], partial: false, expired: [], pending: [] };
+  const step3 = { step: 3, name: 'comparison', differences: [], consistent: false, platform_only: false };
+
+  if (step1.violations.length > 0) {
+    /* §6.3 Step 1: 拒绝汇总 */
+    status = 'unverifiable';
+    step2.skipped = 'step1_unverifiable';
+    step3.skipped = 'step1_unverifiable';
+    notes.push('aggregation refused: Step 1 anchor violation (see unverifiable machines)');
+  } else if (task.cancelled === true) {
+    /* v0.3.0: the operator stopped it. A chosen stop is not a defect. */
+    //
+    // Checked before `unverifiable`-adjacent outcomes and before any timeout: once someone has
+    // deliberately stopped the work, reporting "failed" or "timed out" would describe a decision as
+    // a malfunction, and enough of those trains a reader to ignore the status entirely.
+    status = 'cancelled';
+    step2.skipped = 'task_cancelled';
+    step3.skipped = 'task_cancelled';
+    notes.push(
+      task.cancel_reason ? `cancelled by the operator: ${task.cancel_reason}` : 'cancelled by the operator',
+    );
+  } else if (runnable.length === 0 && expiredMachines.length === 0 && pendingMachines.length === 0 && step0.refused.length > 0) {
+    status = 'refused';
+    step2.skipped = 'all_refused';
+    step3.skipped = 'all_refused';
+  } else if (runnable.length === 0 && expiredMachines.length === 0) {
+    /* v0.3.0: distinguish "still waiting" from "waited long enough". */
+    //
+    // `pending` means the task is live and more envelopes may still arrive. Once the deadline the
+    // caller set has passed and machines are still silent, that is a verdict, and calling it
+    // `pending` forever leaves a reader unable to tell a stuck task from a slow one.
+    const deadline = Number.isFinite(task.deadline_ms) ? task.deadline_ms : 0;
+    if (deadline > 0 && nowMs >= deadline) {
+      status = 'timeout';
+      step2.skipped = 'deadline_passed';
+      step3.skipped = 'deadline_passed';
+      notes.push(
+        `no result envelope by the ${task.timeout_ms}ms deadline (${pendingMachines.length} machine(s) still silent)`,
+      );
+    } else {
+      status = 'pending';
+      step2.skipped = 'no_results_yet';
+      step3.skipped = 'no_results_yet';
+      notes.push('no result envelope has been received yet');
+    }
+  } else {
+    for (const m of runnable) {
+      const s = m.envelope.status;
+      if (s === 'ok') { m.outcome = 'ok'; step2.ok.push(m.machine_id); }
+      else {
+        // {nonzero_exit,timeout,crashed} plus anything outside the §5.1 enum
+        m.outcome = 'failed';
+        explainExecutionFailure(m, s);
+        step2.failed.push({
+          machine_id: m.machine_id,
+          status: s,
+          exit_code: m.envelope.exit_code ?? null,
+          known_failure: FAILURE_STATUSES.includes(s),
+        });
+      }
+    }
+    for (const m of expiredMachines) step2.expired.push(m.machine_id);
+    for (const m of pendingMachines) step2.pending.push(m.machine_id);
+
+    if (step2.expired.length > 0) {
+      /* §4.3: halt=never → booked and marked partial */
+      status = 'partial';
+      step2.partial = true;
+      notes.push(`lease expired on ${step2.expired.length} machine(s) → partial (§4.3)`);
+      step3.skipped = 'lease_expired';
+    } else if (step2.pending.length > 0) {
+      status = 'partial';
+      step2.partial = true;
+      notes.push(`waiting for ${step2.pending.length} machine(s) to report`);
+      step3.skipped = 'machines_pending';
+    } else if (step2.failed.length === 0 && step2.ok.length > 0) {
+      /* §6.3 Step 2: 全部 ok → Step 3 */
+      const okMachines = runnable.filter((m) => m.outcome === 'ok');
+
+      // Compare **within a shard**, not across the whole task.
+      //
+      // `index` is a comparable field, and `split` assigns it per machine by design -- so comparing
+      // every machine against every other made `index` differ on any successful fan-out, and every
+      // split task was reported `divergent`. That is a false alarm on the normal case: `divergent`
+      // tells an operator the machines disagreed, when in fact they did exactly what was asked.
+      //
+      // Grouping by `index` fixes it without special-casing the field: machines meant to produce the
+      // same output are compared with each other, and machines given different slices are not
+      // compared at all. For `replicate` every machine has index 0, so there is a single group and
+      // the behaviour is exactly as before -- which is why the existing 140 relay tests still pass
+      // unchanged.
+      const shards = new Map();
+      for (const m of okMachines) {
+        const key = m.index ?? 0;
+        if (!shards.has(key)) shards.set(key, []);
+        shards.get(key).push(m);
+      }
+
+      const comparable = {};
+      for (const field of COMPARABLE_FIELDS) {
+        comparable[field] = {};
+        for (const m of okMachines) {
+          const v = valueOf(m.envelope, field);
+          if (v !== undefined) comparable[field][m.machine_id] = v;
+        }
+      }
+
+      /**
+       * Fields that differ within some shard, with the shard that disagreed.
+       *
+       * `index` is reported with the shard so a genuine mixed-mode divergence ("shard 0 agreed,
+       * shard 1 did not") stays unambiguous.
+       */
+      const differences = [];
+      for (const [shardIndex, members] of shards) {
+        if (members.length < 2) continue; // one machine cannot disagree with itself
+        for (const field of COMPARABLE_FIELDS) {
+          const values = members.map((m) => canon(valueOf(m.envelope, field)));
+          if (values.some((v) => v !== values[0])) {
+            differences.push({
+              field,
+              index: shardIndex,
+              values: Object.fromEntries(members.map((m) => [m.machine_id, valueOf(m.envelope, field)])),
+            });
+          }
+        }
+      }
+      step3.comparable = comparable;
+      step3.differences = differences;
+
+      /** Metadata drift within any shard, for the `divergent-platform` branch. */
+      const metaDiffers = (field) => {
+        for (const members of shards.values()) {
+          if (members.length < 2) continue;
+          const vals = members.map((m) => canon(valueOf(m.envelope, field)));
+          if (vals.some((v) => v !== vals[0])) return true;
+        }
+        return false;
+      };
+      const platformMetaDiffers = metaDiffers('toolchain') || metaDiffers('platform');
+
+      if (differences.length === 0) {
+        status = 'consistent';
+        step3.consistent = true;
+      } else if (platformMetaDiffers && differences.every((d) => STDOUT_DERIVED_FIELDS.includes(d.field))) {
+        /* §6.3 Step 3: expected — only toolchain/platform differ and the drift is stdout-only */
+        status = 'divergent-platform';
+        step3.platform_only = true;
+        notes.push('divergence is confined to stdout bytes across differing toolchain/platform (expected, no alert)');
+      } else {
+        status = 'divergent';
+        notes.push(`divergent fields: ${differences.map((d) => d.field).join(', ')}`);
+      }
+    } else if (step2.ok.length > 0) {
+      /* v0.3.0 §6.3 Step 2: 部分 ok、部分失败 → degraded */
+      //
+      // This used to be `partial`, which was wrong in a way that mattered: `partial` is also the
+      // answer while machines are still out, so "finished, and half of it failed" was
+      // indistinguishable from "still running" in the one field a reader looks at first. Every
+      // machine here has reported, so the task is over and the verdict is `degraded` -- some of the
+      // work succeeded, the rest did not, and nothing further is coming.
+      status = 'degraded';
+      step2.partial = true;
+      notes.push(`${step2.ok.length} machine(s) succeeded and ${step2.failed.length} failed`);
+    } else {
+      /* §6.3 Step 2: 全部失败 → failed */
+      status = 'failed';
+    }
+  }
+
+  steps.push(step2);
+  steps.push(step3);
+
+  return stripReportAggregate({
+    protocol_version: PROTOCOL_VERSION,
+    task_id: task.task_id,
+    status,
+    computed_at: rfc3339(nowMs),
+    mode: task.mode,
+    index_total: task.index_total,
+    halt: task.halt,
+    write: task.write,
+    created_at: rfc3339(task.created_at_ms),
+    created_by: task.created_by ?? null,
+    cancelled: task.cancelled === true,
+    expected,
+    /**
+     * v0.9.3: whether this task ran against a declared tree at all.
+     *
+     * `expected.base_commit === null` means the dispatcher declared no anchor -- its own tree is not a
+     * git work tree, which is the ordinary case for the plugin running out of a profile directory. The
+     * anchor check is therefore skipped rather than compared against the literal `null` (see Step 1).
+     *
+     * Reported explicitly because the two situations must not look alike: `consistent: true` from an
+     * unanchored run says "these machines agreed with each other", **not** "these machines ran the
+     * tree you meant". An operator comparing results needs to know which of those they are holding.
+     */
+    unanchored: expected.base_commit === null,
+    machines: machines.map((m) => ({
+      machine_id: m.machine_id,
+      machine_name: m.machine_name,
+      index: m.index,
+      attempt: m.attempt,
+      lease_state: m.lease_state,
+      outcome: m.outcome,
+      status: m.envelope?.status ?? null,
+      refusal_reason: m.refusal_reason ?? null,
+      exit_code: m.envelope?.exit_code ?? null,
+      /* v0.4.0: how this machine's envelope travelled, straight off the stored envelope.
+       *
+       * `null` means "the envelope did not say" -- every v0.3.9 result, and the honest answer for a
+       * relay that simply does not know. These two fields are REPORTED, never judged: they are not
+       * in COMPARABLE_FIELDS, so a machine that answered over P2P and one that answered over the
+       * relay still produce the same verdict. A path is not a result. */
+      transport: m.envelope?.transport ?? null,
+      p2p: m.envelope?.p2p ?? null,
+      reasons: m.reasons,
+      // v1.2.6: the relay's verdict, bound to the key registered at pairing.
+      signature_status: m.signature_status ?? null,
+      /**
+       * v1.2.7: the dataflow facts a reader needs to build a reduce plan.
+       *
+       * The aggregate used to publish only a summary per machine, so a client could not see that a result was a blob -- the
+       * reduce plan existed in tests and read raw envelopes that the production response never carried. These four fields are
+       * that omission, closed: the blob hash, the file/blob mode, the inline head, and the byte count.
+       */
+      blob_sha256: m.envelope?.blob_sha256 ?? null,
+      output_mode: m.envelope?.output_mode ?? null,
+      stdout_head: m.envelope?.stdout_head ?? null,
+      stdout_bytes: m.envelope?.stdout_bytes ?? null,
+    })),
+    steps,
+    differences: step3.differences ?? [],
+    notes: expected.base_commit === null
+      ? [...notes, 'no base_commit was declared, so the anchor check did not run: machine agreement here is '
+        + 'agreement with each other, not with a tree the dispatcher named']
+      : notes,
+    counts: {
+      refused: step0.refused.length,
+      unverifiable: step1.violations.length,
+      ok: step2.ok?.length ?? 0,
+      failed: step2.failed?.length ?? 0,
+      expired: step2.expired?.length ?? 0,
+      pending: step2.pending?.length ?? 0,
+    },
+  });
+}
+
+/** Convenience wrapper: pull the task + its results out of a RabbitState. */
+export function aggregateTask(state, taskId, opts = {}) {
+  const task = state.getTask(taskId);
+  if (!task) throw new ProtocolError('NOT_FOUND', 'unknown task_id', { task_id: taskId });
+  return aggregate(task, state.results.values(), opts);
+}
+
+const STATUS_LABEL = Object.freeze({
+  consistent: '✅ consistent',
+  divergent: '❌ divergent',
+  'divergent-platform': '🟡 divergent-platform',
+  failed: '❌ failed',
+  partial: '🟠 partial',
+  unverifiable: '⚠️ unverifiable',
+  // v0.3.0 verdicts. Each keeps a distinct shape because these are read at a glance: `partial`
+  // (still out), `degraded` (finished badly) and `timeout` (never answered) must not look alike.
+  degraded: '🟧 degraded',
+  timeout: '⏱️ timeout',
+  cancelled: '🚫 cancelled',
+  refused: '⛔ refused',
+  pending: '⏳ pending',
+});
+
+function fmt(value) {
+  if (value === undefined) return '—';
+  if (value === null) return 'null';
+  if (typeof value === 'string') return value.length > 80 ? `${value.slice(0, 79)}…` : value;
+  return truncate(jcs(value), 80);
+}
+
+/** Markdown summary report (GET /v1/tasks/{id}/report?format=md). */
+export function renderReportMarkdown(agg, task = null) {
+  const L = [];
+  L.push(`# W2M 汇总报告 — \`${agg.task_id}\``);
+  L.push('');
+  L.push(`**判定：${STATUS_LABEL[agg.status] ?? agg.status}**`);
+  L.push('');
+  L.push('| 字段 | 值 |');
+  L.push('|---|---|');
+  L.push(`| protocol_version | ${agg.protocol_version} |`);
+  L.push(`| 模式 | ${agg.mode} |`);
+  L.push(`| index_total | ${agg.index_total} |`);
+  L.push(`| 写入 | ${agg.write} |`);
+  L.push(`| halt | ${agg.halt} |`);
+  L.push(`| 创建者 | ${fmt(agg.created_by)} |`);
+  L.push(`| 创建时间 | ${agg.created_at} |`);
+  L.push(`| 汇总时间 | ${agg.computed_at} |`);
+  L.push(`| base_commit | \`${fmt(agg.expected.base_commit)}\` |`);
+  L.push(`| base_tree | \`${fmt(agg.expected.base_tree)}\` |`);
+  L.push(`| command_hash | \`${fmt(agg.expected.command_hash)}\` |`);
+  L.push('');
+  L.push('## 逐机结果');
+  L.push('');
+  L.push('| machine_id | index | lease | 判定 | status | exit_code | 说明 | 路径 |');
+  L.push('|---|---|---|---|---|---|---|---|');
+  for (const m of agg.machines) {
+    // v0.4.0: the trailing 路径 column is APPENDED, so every existing column keeps its name and
+    // position and a reader written against v0.3.9 output is unaffected. `-` is "the envelope did
+    // not say" (every v0.3.9 result), which is not the same claim as `relay`.
+    L.push(`| \`${m.machine_id}\` | ${fmt(m.index)} | ${m.lease_state} | ${m.outcome ?? '—'} | ${fmt(m.status)} `
+      + `| ${fmt(m.exit_code)} | ${m.reasons.length ? m.reasons.join('; ') : (m.refusal_reason ?? '')} `
+      + `| ${m.transport ?? '-'} |`);
+  }
+  L.push('');
+  if (agg.differences.length > 0) {
+    L.push('## 可比字段差异');
+    L.push('');
+    for (const d of agg.differences) {
+      L.push(`### \`${d.field}\``);
+      L.push('');
+      L.push('| machine_id | value |');
+      L.push('|---|---|');
+      for (const [machine, value] of Object.entries(d.values)) {
+        L.push(`| \`${machine}\` | \`${fmt(value)}\` |`);
+      }
+      L.push('');
+    }
+  }
+  L.push('## 判定步骤（§6.3，顺序不可合并）');
+  L.push('');
+  for (const s of agg.steps) {
+    L.push(`- **Step ${s.step} · ${s.name}** — ${truncate(jcs(s), 400)}`);
+  }
+  L.push('');
+  if (agg.notes.length > 0) {
+    L.push('## 备注');
+    L.push('');
+    for (const n of agg.notes) L.push(`- ${n}`);
+    L.push('');
+  }
+  if (task) {
+    L.push('## 原始命令');
+    L.push('');
+    L.push('```');
+    L.push(jcs(task.command_argv));
+    L.push('```');
+    L.push('');
+  }
+  return L.join('\n');
+}
+
+/** JSON report (GET /v1/tasks/{id}/report?format=json). */
+export function renderReportJson(agg) {
+  return JSON.stringify(agg, null, 2);
+}
+
+/**
+ * Build a report of the requested format.
+ * @returns {{contentType:string, body:string, aggregate:object}}
+ */
+export function buildReport(state, taskId, { format = 'json', nowMs } = {}) {
+  const agg = aggregateTask(state, taskId, { nowMs });
+  const task = state.getTask(taskId);
+  if (format === 'md' || format === 'markdown') {
+    return { contentType: 'text/markdown; charset=utf-8', body: renderReportMarkdown(agg, task), aggregate: agg };
+  }
+  if (format === 'json') {
+    return { contentType: 'application/json; charset=utf-8', body: renderReportJson(agg), aggregate: agg };
+  }
+  throw new ProtocolError('BAD_REQUEST', 'format must be md|json', { format });
+}
+
+/** Machine-readable verdict used by GET /v1/tasks/{id}. */
+export function taskStatus(state, taskId, opts = {}) {
+  return aggregateTask(state, taskId, opts);
+}