@semalt-ai/code 1.19.0 → 1.20.1

package/test/render-operation.test.js

@@ -0,0 +1,317 @@
+'use strict';
+
+// Output Refactor — Phase 1: ToolOperation descriptor + pure renderOperation.
+//
+// This phase introduces a single descriptor → one pure renderer as the spine
+// for the interactive core tool line (shell/file/generic), replacing inline
+// formatToolLine/buildExecutionDiff assembly at the chat-turn call sites. It
+// must change NOTHING the user sees. These tests are the proof:
+//
+//   1. CHARACTERIZATION — pins the EXACT current bytes (glyphs, spacing, ANSI)
+//      for each representative path. Written against the captured output; they
+//      are the regression anchor.
+//   2. EQUIVALENCE — renderOperation(buildToolOperation(x)) is byte-for-byte
+//      identical to the old formatToolLine(x) / buildExecutionDiff(x) for every
+//      path. This is the phase's pass/fail.
+//   3. DESCRIPTOR DERIVATION — the descriptor is built correctly from the
+//      normalized [action, ...opts] tuple for each category, both rails.
+//
+// Phase 2.5 update: the PINNED bytes were re-pinned to the saturated palette.
+// The line STRUCTURE is unchanged — only colour codes differ (see PINNED).
+//
+// Phase 3 update: the RUNNING (pending, non-blocking) glyph is now an animated
+// spinner frame (the `tool` SPINNER_DEF) instead of the static dot, with the
+// frame derived from durationMs (floor(ms/100) % frames.length). The blocking
+// pending glyph (ask_user, noDuration) stays the static dot. Only those two
+// running-phase glyphs changed; everything else is byte-identical (see PINNED).
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+// Phase 2.5: colour is gated on `isTTY && !NO_COLOR`. Force a colour-capable
+// environment so the characterization bytes below are stable regardless of how
+// the test runner wires stdout. (node:test runs each file in its own process,
+// so this mutation does not leak to other suites.)
+process.stdout.isTTY = true;
+delete process.env.NO_COLOR;
+
+const { formatToolLine } = require('../lib/ui/format');
+const { buildExecutionDiff } = require('../lib/ui/diff');
+const { buildToolOperation, serializeOperation } = require('../lib/ui/tool-operation');
+const { renderOperation } = require('../lib/ui/render-operation');
+
+// ---------------------------------------------------------------------------
+// Representative tool-call lifecycle paths. `spec` is the data available at the
+// onToolStart/onToolEnd callbacks; `phase` is which line we render.
+// ---------------------------------------------------------------------------
+const PATHS = [
+  { name: 'shell pending',          phase: 'pending', spec: { status: 'pending', tag: 'shell', arg: 'npm install', attrs: { command: 'npm install' }, durationMs: 1500 } },
+  { name: 'shell result (ok)',      phase: 'result',  spec: { status: 'success', tag: 'shell', arg: 'npm install', attrs: { command: 'npm install' }, durationMs: 2300, meta: { exit_code: 0 } } },
+  { name: 'shell result (error)',   phase: 'result',  spec: { status: 'failure', tag: 'shell', arg: 'npm test', attrs: { command: 'npm test' }, durationMs: 800, meta: { exit_code: 1 }, error: { message: 'exit 1', code: 1 } } },
+  { name: 'file edit pending',      phase: 'pending', spec: { status: 'pending', tag: 'write_file', arg: 'src/app.js', attrs: { path: 'src/app.js' }, durationMs: 100 } },
+  { name: 'file edit result (ok)',  phase: 'result',  spec: { status: 'success', tag: 'write_file', arg: 'src/app.js', attrs: { path: 'src/app.js' }, durationMs: 50, meta: { bytes: 2048 } } },
+  { name: 'http error result',      phase: 'result',  spec: { status: 'failure', tag: 'http_get', arg: 'https://x.example', attrs: { url: 'https://x.example' }, durationMs: 5000, error: { message: 'Request timeout', code: 'ETIMEDOUT' } } },
+  { name: 'ask_user (blocking)',    phase: 'pending', spec: { status: 'pending', tag: 'ask_user', arg: 'Proceed?', attrs: { question: 'Proceed?' }, noDuration: true } },
+  { name: 'MCP tool result',        phase: 'result',  spec: { status: 'success', tag: 'mcp__server__lookup', arg: 'q', attrs: {}, durationMs: 120 } },
+  { name: 'subagent result',        phase: 'result',  spec: { status: 'success', tag: 'spawn_agent', arg: 'task', attrs: {}, durationMs: 9000 } },
+];
+
+// The OLD call site: how chat-turn assembled formatToolLine args before Phase 1.
+// pending lines carry no meta/error; result lines carry both.
+function oldFormat(spec, phase) {
+  return formatToolLine({
+    status: spec.status,
+    tag: spec.tag,
+    arg: spec.arg,
+    attrs: spec.attrs,
+    durationMs: spec.durationMs,
+    meta: phase === 'pending' ? undefined : spec.meta,
+    error: phase === 'pending' ? undefined : spec.error,
+    noDuration: spec.noDuration,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 1. CHARACTERIZATION — the exact current bytes (the regression anchor).
+//
+// Re-pinned to the Phase 2.5 saturated palette (+ the Phase 3 animated running
+// glyph). The line STRUCTURE is identical to Phase 1/2 (spacing, segments,
+// separators); the result/blocking glyphs are unchanged, only the running glyph
+// now animates. Phase 2.5 colour codes: categories saturated + differentiated
+// (shell 214, file 77,
+// net 39, mcp 141 with its own "mcp" label, tool fallback 245), statuses
+// saturated (ok 40, error 203), the pending glyph category-tinted (never gray),
+// the operation text now painted in the category colour, and durations lifted
+// to subtle 244.
+// ---------------------------------------------------------------------------
+const PINNED = {
+  'shell pending':         '  \x1b[38;5;214m⣷\x1b[0m \x1b[38;5;214mshell\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;214mnpm install\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244m1.5s…\x1b[0m',
+  'shell result (ok)':     '  \x1b[38;5;40m✓\x1b[0m \x1b[38;5;214mshell\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;214mnpm install\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244m2.3s\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244mexit 0\x1b[0m',
+  'shell result (error)':  '  \x1b[38;5;203m✗\x1b[0m \x1b[38;5;214mshell\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;214mnpm test\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;203m800ms\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;203mexit 1\x1b[0m',
+  'file edit pending':     '  \x1b[38;5;77m⣽\x1b[0m \x1b[38;5;77mfile \x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;77mwrite src/app.js\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244m100ms…\x1b[0m',
+  'file edit result (ok)': '  \x1b[38;5;40m✓\x1b[0m \x1b[38;5;77mfile \x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;77mwrite src/app.js\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244m50ms\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244m2.0 KB\x1b[0m',
+  'http error result':     '  \x1b[38;5;203m✗\x1b[0m \x1b[38;5;39mnet  \x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;39mGET https://x.example\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;203m5.0s\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;203mtimeout\x1b[0m',
+  'ask_user (blocking)':   '  \x1b[38;5;211m●\x1b[0m \x1b[38;5;211muser \x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;211mask Proceed?\x1b[0m',
+  'MCP tool result':       '  \x1b[38;5;40m✓\x1b[0m \x1b[38;5;141mmcp  \x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;141mmcp__server__lookup q\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244m120ms\x1b[0m',
+  'subagent result':       '  \x1b[38;5;40m✓\x1b[0m \x1b[38;5;245mtool \x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;245mspawn_agent task\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244m9.0s\x1b[0m',
+};
+
+for (const { name, phase, spec } of PATHS) {
+  test(`characterization: '${name}' bytes are pinned`, () => {
+    assert.strictEqual(oldFormat(spec, phase), PINNED[name], 'current formatter output drifted from pinned bytes');
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 2. EQUIVALENCE — descriptor→renderer == old formatter, byte-for-byte.
+// ---------------------------------------------------------------------------
+for (const { name, phase, spec } of PATHS) {
+  test(`equivalence: '${name}' renderOperation == formatToolLine`, () => {
+    const op = buildToolOperation(spec);
+    const rendered = renderOperation(op, { mode: 'ansi', phase });
+    assert.strictEqual(rendered, oldFormat(spec, phase), 'renderer diverged from the old formatter');
+    // …and therefore equals the pinned bytes too.
+    assert.strictEqual(rendered, PINNED[name]);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 2b. EQUIVALENCE — the diff detail body (file edit) renders identically.
+// ---------------------------------------------------------------------------
+test('equivalence: diff detail == buildExecutionDiff', () => {
+  const diff = { before: 'a\nb\nc\n', after: 'a\nB\nc\n', path: 'lib/x.js' };
+  const op = buildToolOperation({ tag: 'edit_file', arg: 'lib/x.js', attrs: { path: 'lib/x.js' }, status: 'ok', diff, durationMs: 7 });
+  const rendered = renderOperation(op, { mode: 'ansi', phase: 'detail', maxLines: 50 });
+  const old = buildExecutionDiff({ diff, maxLines: 50 });
+  assert.strictEqual(rendered, old);
+  assert.ok(rendered.length > 0, 'a real change renders a non-empty diff');
+});
+
+test('equivalence: a no-op diff yields no detail (matches buildExecutionDiff null)', () => {
+  const diff = { before: 'same\n', after: 'same\n', path: 'x' };
+  const op = buildToolOperation({ tag: 'edit_file', arg: 'x', attrs: { path: 'x' }, status: 'ok', diff });
+  // buildExecutionDiff returns null for an unchanged edit; the renderer returns ''.
+  assert.strictEqual(buildExecutionDiff({ diff, maxLines: 50 }), null);
+  assert.strictEqual(renderOperation(op, { mode: 'ansi', phase: 'detail', maxLines: 50 }), '');
+});
+
+// ---------------------------------------------------------------------------
+// 3. DESCRIPTOR DERIVATION — built correctly from the normalized tuple. Both
+// the XML rail and the native rail converge on the SAME [action, ...opts]
+// tuple, so a descriptor built from that tuple is rail-agnostic by construction.
+// ---------------------------------------------------------------------------
+
+test('descriptor: shell category/target/status/glyph from the tuple', () => {
+  const op = buildToolOperation({ tag: 'shell', arg: 'ls -la', attrs: { command: 'ls -la' }, status: 'ok', durationMs: 30, meta: { exit_code: 0 } });
+  assert.strictEqual(op.category, 'shell');
+  assert.strictEqual(op.target, 'ls -la');
+  assert.strictEqual(op.status, 'ok');
+  assert.strictEqual(op.glyph, '✓');
+  assert.deepStrictEqual(op.meta, { exit_code: 0 });
+  assert.strictEqual(op.detail, null);
+});
+
+test('descriptor: file edit carries a diff detail when present', () => {
+  const diff = { before: '1\n', after: '2\n', path: 'f' };
+  const op = buildToolOperation({ tag: 'write_file', arg: 'f', attrs: { path: 'f' }, status: 'ok', diff });
+  assert.strictEqual(op.category, 'file');
+  assert.strictEqual(op.detail.kind, 'diff');
+  assert.deepStrictEqual(op.detail.payload, { before: '1\n', after: '2\n', path: 'f' });
+});
+
+test('descriptor: status normalization — success/failure → ok/error, error forces error', () => {
+  assert.strictEqual(buildToolOperation({ tag: 'shell', status: 'success' }).status, 'ok');
+  assert.strictEqual(buildToolOperation({ tag: 'shell', status: 'failure' }).status, 'error');
+  assert.strictEqual(buildToolOperation({ tag: 'shell', status: 'ok', error: { message: 'x' } }).status, 'error');
+  assert.strictEqual(buildToolOperation({ tag: 'shell', status: 'pending' }).status, 'pending');
+});
+
+test('descriptor: glyph tracks status', () => {
+  assert.strictEqual(buildToolOperation({ tag: 'shell', status: 'pending' }).glyph, '●');
+  assert.strictEqual(buildToolOperation({ tag: 'shell', status: 'ok' }).glyph, '✓');
+  assert.strictEqual(buildToolOperation({ tag: 'shell', status: 'failure' }).glyph, '✗');
+});
+
+test('descriptor: net category for http_get; error status suppresses diff detail', () => {
+  const op = buildToolOperation({ tag: 'http_get', arg: 'https://x', attrs: { url: 'https://x' }, status: 'error', error: { message: 'boom' }, diff: { before: 'a', after: 'b', path: 'p' } });
+  assert.strictEqual(op.category, 'net');
+  assert.strictEqual(op.detail, null, 'a failed op carries no diff detail');
+});
+
+test('descriptor: git_* and mcp tags resolve to their own categories (no longer the tool fallback)', () => {
+  assert.strictEqual(buildToolOperation({ tag: 'git_commit', status: 'ok' }).category, 'git');
+  assert.strictEqual(buildToolOperation({ tag: 'mcp__srv__do', arg: 'x', attrs: {}, status: 'ok' }).category, 'mcp');
+});
+
+test('descriptor: a truly unknown tag falls back to the tool category; is frozen', () => {
+  const op = buildToolOperation({ tag: 'spawn_agent', arg: 'x', attrs: {}, status: 'ok' });
+  assert.strictEqual(op.category, 'tool');
+  assert.ok(Object.isFrozen(op), 'descriptor is immutable');
+});
+
+test('descriptor: action-name tuple (read/write/append/exec) normalizes for category', () => {
+  // The native rail may hand action names that differ from tag names; the
+  // descriptor normalizes them the same way the renderer does.
+  assert.strictEqual(buildToolOperation({ tag: 'exec', status: 'ok' }).category, 'shell');
+  assert.strictEqual(buildToolOperation({ tag: 'read', status: 'ok' }).category, 'file');
+  assert.strictEqual(buildToolOperation({ tag: 'write', status: 'ok' }).category, 'file');
+});
+
+// ---------------------------------------------------------------------------
+// Renderer guards: unknown mode/empty descriptor degrade safely (no throw).
+// ---------------------------------------------------------------------------
+test('renderOperation: unknown mode and null descriptor degrade safely', () => {
+  // null descriptor → '' in every mode (guard: no throw on absent op).
+  assert.strictEqual(renderOperation(null, { mode: 'ansi', phase: 'result' }), '');
+  assert.strictEqual(renderOperation(null, { mode: 'json' }), '');
+  // an unknown mode falls through to '' (guard: forward-compat, never throw).
+  const op = buildToolOperation({ tag: 'shell', status: 'ok', durationMs: 1 });
+  assert.strictEqual(renderOperation(op, { mode: 'totally-unknown' }), '');
+});
+
+// ---------------------------------------------------------------------------
+// Phase 6d-i: json/event are PURE structured-data modes over the descriptor,
+// built from the SAME operationCore as serializeOperation (one serializer). They
+// emit ZERO ANSI, do no IO, and add no framing — that is the headless sink's job
+// (6d-ii). The descriptors below cover a normal op, an error op, and a diff op.
+// ---------------------------------------------------------------------------
+const JSON_OPS = {
+  'normal tool': buildToolOperation({ status: 'success', tag: 'shell', arg: 'npm install', attrs: { command: 'npm install' }, durationMs: 2300, meta: { exit_code: 0 } }),
+  'error op':    buildToolOperation({ status: 'failure', tag: 'http_get', arg: 'https://x.example', attrs: { url: 'https://x.example' }, durationMs: 5000, error: { message: 'Request timeout', code: 'ETIMEDOUT' } }),
+  'diff op':     buildToolOperation({ tag: 'edit_file', arg: 'lib/x.js', attrs: { path: 'lib/x.js' }, status: 'ok', diff: { before: 'a\nb\nc\n', after: 'a\nB\nc\n', path: 'lib/x.js' }, durationMs: 7 }),
+};
+
+// 1. json structure — descriptor-native fields with the RIGHT VALUES (not just
+//    presence). The whole object is asserted by deep-equality against the
+//    descriptor's own core (no `v`, no `id`/`glyph` live fields, no ANSI).
+test('json: structured descriptor object with correct field VALUES', () => {
+  assert.deepStrictEqual(renderOperation(JSON_OPS['normal tool'], { mode: 'json' }), {
+    tag: 'shell', target: 'npm install', attrs: { command: 'npm install' }, category: 'shell',
+    status: 'ok', durationMs: 2300, meta: { exit_code: 0 }, error: null, noDuration: false, detail: null,
+  });
+  assert.deepStrictEqual(renderOperation(JSON_OPS['error op'], { mode: 'json' }), {
+    tag: 'http_get', target: 'https://x.example', attrs: { url: 'https://x.example' }, category: 'net',
+    status: 'error', durationMs: 5000, meta: null, error: { message: 'Request timeout', code: 'ETIMEDOUT' },
+    noDuration: false, detail: null,
+  });
+  assert.deepStrictEqual(renderOperation(JSON_OPS['diff op'], { mode: 'json' }), {
+    tag: 'edit_file', target: 'lib/x.js', attrs: { path: 'lib/x.js' }, category: 'file', status: 'ok',
+    durationMs: 7, meta: null, error: null, noDuration: false,
+    detail: { kind: 'diff', payload: { before: 'a\nb\nc\n', after: 'a\nB\nc\n', path: 'lib/x.js' } },
+  });
+  // No live-only / persistence-only fields leak into the embeddable form.
+  for (const op of Object.values(JSON_OPS)) {
+    const j = renderOperation(op, { mode: 'json' });
+    assert.ok(!('id' in j) && !('glyph' in j) && !('v' in j), 'json drops id/glyph/v');
+  }
+});
+
+// 2. event structure — the json object PLUS the lifecycle `phase` it rendered
+//    for, and NOTHING ELSE. (Defined relationship: event === { ...json, phase }.)
+test('event: json object plus the lifecycle phase, and nothing else', () => {
+  for (const [name, op] of Object.entries(JSON_OPS)) {
+    const json = renderOperation(op, { mode: 'json' });
+    const event = renderOperation(op, { mode: 'event', phase: 'result' });
+    assert.deepStrictEqual(event, { ...json, phase: 'result' }, `event == {...json, phase} for '${name}'`);
+  }
+  // phase is carried through verbatim; default is 'result' when omitted.
+  assert.strictEqual(renderOperation(JSON_OPS['normal tool'], { mode: 'event', phase: 'pending' }).phase, 'pending');
+  assert.strictEqual(renderOperation(JSON_OPS['normal tool'], { mode: 'event' }).phase, 'result');
+});
+
+// 3. single source of truth — json's persistable overlap with serializeOperation
+//    is IDENTICAL (they share one operationCore; serialize only adds `v`). Proven
+//    on the overlapping keys so the one-mapping invariant can't silently diverge.
+test('json: persistable overlap is identical to serializeOperation (one mapping)', () => {
+  for (const op of Object.values(JSON_OPS)) {
+    const json = renderOperation(op, { mode: 'json' });
+    const ser = serializeOperation(op);
+    const overlap = {};
+    for (const k of Object.keys(json)) overlap[k] = ser[k];
+    assert.deepStrictEqual(json, overlap, 'json == serializeOperation on shared keys');
+    // serialize is exactly json + the `v` persistence tag — no other difference.
+    assert.deepStrictEqual(ser, { v: 1, ...json });
+  }
+});
+
+// 4a. ANTI-PING-PONG — serializeOperation output is byte-identical to before this
+//     commit (snapshots captured pre-6d-i). Guards replay/persistence (6a–6c).
+test('anti-ping-pong: serializeOperation bytes are pinned (replay/persist guard)', () => {
+  const SER_PINNED = {
+    'normal tool': '{"v":1,"tag":"shell","target":"npm install","attrs":{"command":"npm install"},"category":"shell","status":"ok","durationMs":2300,"meta":{"exit_code":0},"error":null,"noDuration":false,"detail":null}',
+    'error op':    '{"v":1,"tag":"http_get","target":"https://x.example","attrs":{"url":"https://x.example"},"category":"net","status":"error","durationMs":5000,"meta":null,"error":{"message":"Request timeout","code":"ETIMEDOUT"},"noDuration":false,"detail":null}',
+    'diff op':     '{"v":1,"tag":"edit_file","target":"lib/x.js","attrs":{"path":"lib/x.js"},"category":"file","status":"ok","durationMs":7,"meta":null,"error":null,"noDuration":false,"detail":{"kind":"diff","payload":{"before":"a\\nb\\nc\\n","after":"a\\nB\\nc\\n","path":"lib/x.js"}}}',
+  };
+  for (const [name, op] of Object.entries(JSON_OPS)) {
+    assert.strictEqual(JSON.stringify(serializeOperation(op)), SER_PINNED[name], `serialize bytes drifted for '${name}'`);
+  }
+});
+
+// 4b. ANTI-PING-PONG — the ansi render is byte-identical to before. Guards the
+//     interactive path (Phase 1). Re-uses the PINNED table above as the anchor.
+test('anti-ping-pong: ansi render bytes are pinned (interactive path guard)', () => {
+  for (const { name, phase, spec } of PATHS) {
+    const op = buildToolOperation(spec);
+    assert.strictEqual(renderOperation(op, { mode: 'ansi', phase }), PINNED[name], `ansi bytes drifted for '${name}'`);
+  }
+});
+
+// 5. PURITY — json/event carry no ANSI escape sequences and the calls perform no
+//    stdout IO (the renderer must not write; framing/IO is the consumer's job).
+test('purity: json/event contain no ANSI and write nothing to stdout', () => {
+  const ESC = /\x1b\[/;
+  const origWrite = process.stdout.write;
+  let wrote = 0;
+  process.stdout.write = function () { wrote++; return true; };
+  try {
+    for (const op of Object.values(JSON_OPS)) {
+      const j = renderOperation(op, { mode: 'json' });
+      const e = renderOperation(op, { mode: 'event', phase: 'result' });
+      assert.ok(!ESC.test(JSON.stringify(j)), 'json has no ANSI');
+      assert.ok(!ESC.test(JSON.stringify(e)), 'event has no ANSI');
+    }
+  } finally {
+    process.stdout.write = origWrite;
+  }
+  assert.strictEqual(wrote, 0, 'json/event modes performed no stdout IO');
+});

package/test/replay-descriptor-xml.test.js

@@ -0,0 +1,216 @@
+'use strict';
+
+// Output Refactor — Phase 6b: XML-rail replay parity via a persisted descriptor array.
+//
+// The XML rail folds ALL tool results of a turn into ONE {role:'user'} feedback
+// blob (agent.js): `Tool execution results:\n\n${results.join('\n\n')}\n\n…`. On
+// replay that blob was rendered as a single lossy summarizeToolResult line — no
+// per-call diff/duration/status. It cannot be split back by parsing (the only
+// separator, \n\n, appears freely inside result bodies). Phase 6b persists the
+// per-call display descriptors as a sibling `_display[]` aligned 1:1 with the
+// results and, ON A GATE, replays each through the SAME native-rail render. The
+// gate is the crux: per-call rendering happens ONLY when every slot is a
+// non-null known-version core; any `null` (a web op — out of scope until 6c) or
+// unknown version drops the whole blob to the unchanged legacy summary.
+//
+// These tests pin:
+//   1. POSITIVE — an all-non-null `_display[]` replays as N per-call lines,
+//      byte-identical to the native rail render of each descriptor, in order.
+//   2. NEGATIVE / no-regression gate — no `_display`, a `null` slot, and an
+//      unknown-version slot ALL fall back to the unchanged whole-blob summary.
+//   3. INV.1 — attaching `_display[]` leaves the feedback `content` byte-identical.
+//   4. ANTI-PING-PONG — native (6a) and Phase 1 fresh-render bytes are unchanged.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+// Force a colour-capable env so byte comparisons are stable (node:test runs each
+// file in its own process — no leak to other suites). Mirrors the 6a suite.
+process.stdout.isTTY = true;
+delete process.env.NO_COLOR;
+
+const { buildToolOperation, serializeOperation, descriptorFromStored } = require('../lib/ui/tool-operation');
+const { renderOperation } = require('../lib/ui/render-operation');
+const { ChatHistory } = require('../lib/ui/chat-history');
+const { summarizeToolResult } = require('../lib/ui/format');
+const { createChatSession } = require('../lib/commands/chat-session');
+
+const stripAnsi = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, '');
+
+// ── Fixtures: completed ops spanning the fidelity dimensions the summary drops —
+// a file-edit DIFF, a SHELL ERROR, and a plain SHELL OK, with distinct durations.
+const EDIT_DIFF = buildToolOperation({
+  id: 'tool-1', tag: 'edit_file', arg: 'lib/x.js', attrs: { path: 'lib/x.js' },
+  status: 'ok', durationMs: 12, diff: { before: 'a\nb\nc\n', after: 'a\nB\nc\n', path: 'lib/x.js' },
+});
+const SHELL_ERR = buildToolOperation({
+  id: 'tool-2', tag: 'shell', arg: 'npm test', attrs: { command: 'npm test' },
+  status: 'error', durationMs: 800, meta: { exit_code: 1 }, error: { message: 'exit 1', code: 1 },
+});
+const SHELL_OK = buildToolOperation({
+  id: 'tool-3', tag: 'shell', arg: 'npm run lint', attrs: { command: 'npm run lint' },
+  status: 'ok', durationMs: 2300, meta: { exit_code: 0 },
+});
+
+const CFG = { diff_max_lines: 50, shell_preview_lines: 5 };
+
+// Build the XML feedback blob EXACTLY as agent.js does, with an optional aligned
+// `_display[]`. `results` are arbitrary per-call body strings (their bytes are
+// irrelevant to display when a descriptor restores — only `content` identity is).
+function xmlBlob(results, display) {
+  const m = {
+    role: 'user',
+    content: `Tool execution results:\n\n${results.join('\n\n')}\n\nContinue with the task. If everything is done, summarize what was accomplished.`,
+  };
+  if (display !== undefined) m._display = display;
+  return m;
+}
+
+// Drive the REAL replay function (chat-session.displayLoadedMessages) over one
+// loaded message and capture exactly what gets committed to scrollback. Only
+// `chatHistory` + `getConfig` are exercised by the blob branch under test.
+function replay(loadedMessage, cfg) {
+  const ch = new ChatHistory();
+  const out = [];
+  ch._commit = (t) => out.push(t);
+  const session = createChatSession({ chatHistory: ch, getConfig: () => cfg || CFG });
+  session.displayLoadedMessages([loadedMessage]);
+  return out.join('');
+}
+
+// Oracle: what the NATIVE rail commits for one descriptor core (the exact path a
+// per-call XML line must reproduce). Renders through addMessage so it includes
+// the result line + any diff/output detail chrome, byte-for-byte.
+function nativeReplay(core, cfg) {
+  const c = cfg || CFG;
+  const ch = new ChatHistory();
+  const out = [];
+  ch._commit = (t) => out.push(t);
+  ch.addMessage({
+    role: 'tool', tag: 'tool', content: '', _display: core,
+    diffMaxLines: c.diff_max_lines, previewLines: c.shell_preview_lines || 5,
+  });
+  return out.join('');
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// 1. POSITIVE — all-non-null `_display[]` → N per-call lines, byte-identical to
+//    the native render of each descriptor, in call order (guards XML parity).
+// ───────────────────────────────────────────────────────────────────────────
+test('replay: XML blob with all-non-null _display[] renders N per-call lines == native render, in order (guards XML per-call parity)', () => {
+  const cores = [serializeOperation(EDIT_DIFF), serializeOperation(SHELL_ERR), serializeOperation(SHELL_OK)];
+  const committed = replay(xmlBlob(['edited lib/x.js', 'FAIL', 'lint clean'], cores), CFG);
+
+  // Byte-identical to concatenating the native rail's render of each descriptor.
+  const expected = cores.map((c) => nativeReplay(c, CFG)).join('');
+  assert.strictEqual(committed, expected, 'per-call lines are byte-identical to the native rail, in call order');
+
+  // And it is not vacuous: the fidelity the summary drops is actually present.
+  const text = stripAnsi(committed);
+  assert.match(text, /2\.3s/, 'shell-ok real duration shown');
+  assert.match(text, /exit 0/, 'shell-ok real exit meta shown');
+  assert.match(text, /exit 1/, 'shell-error real exit meta shown');
+  // The edit diff body renders (a line removed / a line added).
+  const diffBody = renderOperation(descriptorFromStored(cores[0]), { mode: 'ansi', phase: 'detail', maxLines: 50 });
+  assert.ok(diffBody.length > 0 && committed.includes(diffBody), 'the edit diff body is replayed in full');
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// 2. NEGATIVE / no-regression gate — no `_display`, a `null` slot, and an
+//    unknown-version slot all fall back to the SAME unchanged whole-blob summary.
+// ───────────────────────────────────────────────────────────────────────────
+
+// Snapshot oracle for today's whole-blob behaviour (header/footer stripped,
+// collapsed via summarizeToolResult — exactly the legacy fall-through).
+function legacyWholeBlob(blobMsg) {
+  const raw = blobMsg.content;
+  const body = raw
+    .replace(/^Tool execution results[^\n]*\n+/, '')
+    .replace(/\n+Continue with the task\.[\s\S]*$/, '')
+    .trim();
+  const ch = new ChatHistory();
+  const out = [];
+  ch._commit = (t) => out.push(t);
+  ch.addMessage({ role: 'tool', tag: 'tool', content: body || raw });
+  return out.join('');
+}
+
+test('replay: XML blob with NO _display falls back to the whole-blob summary, byte-identical to today (guards legacy fallback)', () => {
+  const blob = xmlBlob(['Command `npm test`:\nExit code: 0\nall good']); // no _display
+  const committed = replay(blob, CFG);
+  assert.strictEqual(committed, legacyWholeBlob(blob), 'no-_display replay is byte-identical to the legacy whole-blob summary');
+});
+
+test('replay: XML blob whose _display[] has ONE null slot falls back to the whole-blob summary (guards web no-regression)', () => {
+  // A null slot stands in for a web op (intercepted away from buildToolOperation,
+  // out of scope until 6c). Rendering only the non-null slots would make the web
+  // op vanish — so the WHOLE blob must stay on the legacy summary.
+  const blob = xmlBlob(
+    ['edited lib/x.js', 'fetched https://example.com'],
+    [serializeOperation(EDIT_DIFF), null],
+  );
+  const committed = replay(blob, CFG);
+  assert.strictEqual(committed, legacyWholeBlob(blob), 'one null slot → unchanged whole-blob summary');
+  // It must NOT render the non-null EDIT_DIFF slot individually.
+  const diffBody = renderOperation(descriptorFromStored(serializeOperation(EDIT_DIFF)), { mode: 'ansi', phase: 'detail', maxLines: 50 });
+  assert.ok(diffBody.length > 0, 'precondition: the edit slot has a diff body that would have shown');
+  assert.ok(!committed.includes(diffBody), 'no partial render — the non-null slot is NOT rendered individually');
+});
+
+test('replay: XML blob whose _display[] has an unknown-version (v:999) slot falls back to the whole-blob summary (guards version gate)', () => {
+  const blob = xmlBlob(
+    ['edited lib/x.js', 'something'],
+    [serializeOperation(EDIT_DIFF), { v: 999, tag: 'shell', status: 'ok' }],
+  );
+  const committed = replay(blob, CFG);
+  assert.strictEqual(committed, legacyWholeBlob(blob), 'unknown-version slot → unchanged whole-blob summary');
+  // Sanity: the summary path was taken (the collapsed one-liner is present).
+  const body = blob.content
+    .replace(/^Tool execution results[^\n]*\n+/, '')
+    .replace(/\n+Continue with the task\.[\s\S]*$/, '')
+    .trim();
+  assert.match(stripAnsi(committed), new RegExp(summarizeToolResult(body).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// 3. INV.1 — attaching `_display[]` is additive: the feedback `content` is
+//    byte-identical to the original results.join('\n\n')-wrapped string, and
+//    `_display` carries the aligned array (never folded into content).
+// ───────────────────────────────────────────────────────────────────────────
+test('inv.1: attaching _display[] leaves the feedback content byte-identical (guards the model-facing chokepoint)', () => {
+  const results = ['Command `npm test`:\nExit code: 0\nall good', 'Updated lib/x.js'];
+  const cores = [serializeOperation(SHELL_OK), serializeOperation(EDIT_DIFF)];
+  // Model the agent.js push: content from results.join, _display attached aside.
+  const expectedContent = `Tool execution results:\n\n${results.join('\n\n')}\n\nContinue with the task. If everything is done, summarize what was accomplished.`;
+  const msg = xmlBlob(results, cores);
+  assert.strictEqual(msg.content, expectedContent, 'content equals the results.join-wrapped string, byte-for-byte');
+  assert.ok(!msg.content.includes('_display'), 'no descriptor framing in content');
+  assert.ok(!msg.content.includes('2.3s'), 'no descriptor duration leaked into content');
+  // _display is the aligned array, preserved with its slots.
+  assert.ok(Array.isArray(msg._display) && msg._display.length === 2);
+  assert.strictEqual(msg._display[0].durationMs, 2300);
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// 4. ANTI-PING-PONG — 6b did not regress the native (6a) replay parity nor the
+//    Phase 1 fresh-render bytes (threading the array changed neither path).
+// ───────────────────────────────────────────────────────────────────────────
+test('anti-ping-pong: native (6a) round-trip still byte-identical (guards no 6a regression)', () => {
+  const restored = descriptorFromStored(serializeOperation(EDIT_DIFF));
+  assert.strictEqual(
+    renderOperation(restored, { mode: 'ansi' }),
+    renderOperation(EDIT_DIFF, { mode: 'ansi' }),
+    'native rail result line round-trips byte-identical',
+  );
+});
+
+test('anti-ping-pong: Phase 1 fresh-render bytes unchanged (guards no live-path regression)', () => {
+  const shellOk = renderOperation(
+    buildToolOperation({ status: 'success', tag: 'shell', arg: 'npm install', attrs: { command: 'npm install' }, durationMs: 2300, meta: { exit_code: 0 } }),
+    { mode: 'ansi', phase: 'result' },
+  );
+  assert.strictEqual(
+    shellOk,
+    '  \x1b[38;5;40m✓\x1b[0m \x1b[38;5;214mshell\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;214mnpm install\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244m2.3s\x1b[0m \x1b[2m·\x1b[0m \x1b[38;5;244mexit 0\x1b[0m',
+  );
+});