Let the candidate mark unclear interviewer lines

docs/avatar-contract.md

@@ -332,6 +332,16 @@ Keeping the last turn lets the candidate reread a hint or follow-up question
 while thinking, without switching away from the problem. The Transcript tab
 still keeps every turn.
 
+An "Unclear" button beside the "Live CC:" label marks the Jim turn on screen,
+and pressing it again unmarks it. It shows only while a Jim turn is on screen,
+and once `MAX_UNCLEAR_LINES` (10) turns are marked it is disabled on any turn
+not already marked. Jim is not told about a mark. When the report is saved,
+the marked turns are resolved to their transcript text and stored as
+`unclearLines` in the history entry, outside the report and its request. The
+report and its Markdown export list them, and the export tags them in the
+transcript. A report reopened from Past attempts or a replay keeps the list,
+but its export has no transcript to tag.
+
 Jim captions reveal gradually, even after final text arrives, because
 generation can finish while audio is still queued. An edit during the reveal
 is remembered for that Jim segment: its final text finishes revealing, then

tests/browser/captions.test.js

@@ -1,6 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { functionBody, read } from "./source.js";
+import { MAX_UNCLEAR_LINES } from "../../web/lib.js";
 
 let captionCopies = 0;
 
@@ -671,3 +672,195 @@ test("a pending code edit preserves the candidate idle deadline", async (t) => {
   t.mock.timers.tick(60000);
   assert.equal(nodes.captionsBar.hidden, true);
 });
+
+function fakeUnclearButton() {
+  return {
+    hidden: true,
+    disabled: false,
+    title: "",
+    attributes: {},
+    click: null,
+    setAttribute(name, value) {
+      this.attributes[name] = value;
+    },
+    addEventListener(type, handler) {
+      if (type === "click") this.click = handler;
+    },
+  };
+}
+
+async function setupUnclear(t) {
+  const captions = await import(
+    `../../web/captions.js?copy=${++captionCopies}`
+  );
+  const button = fakeUnclearButton();
+  const nodes = {
+    captionsText: { textContent: "" },
+    captionsBar: { hidden: true },
+    captionUnclear: button,
+  };
+  captions.initCaptions({ nodes });
+  t.mock.timers.enable({ apis: ["setTimeout"] });
+  return { captions, button, nodes };
+}
+
+test("the Unclear button marks and unmarks the current Jim turn", async (t) => {
+  const { captions, button } = await setupUnclear(t);
+
+  captions.updateCaptions("interviewer", "Use a hash map.", "jim-1", {
+    final: true,
+  });
+  assert.equal(button.hidden, false);
+
+  button.click();
+  assert.equal(button.attributes["aria-pressed"], "true");
+  assert.deepEqual(captions.unclearLineIds(), ["jim-1"]);
+
+  button.click();
+  assert.equal(button.attributes["aria-pressed"], "false");
+  assert.deepEqual(captions.unclearLineIds(), []);
+});
+
+test("candidate speech hides the Unclear button and a new Jim turn starts unmarked", async (t) => {
+  const { captions, button } = await setupUnclear(t);
+
+  captions.updateCaptions("interviewer", "Use a hash map.", "jim-1", {
+    final: true,
+  });
+  button.click();
+  captions.updateCaptions("you", "Okay.", "you-1");
+  assert.equal(button.hidden, true);
+
+  captions.updateCaptions("interviewer", "Try sorting.", "jim-2");
+  assert.equal(button.hidden, false);
+  assert.equal(button.attributes["aria-pressed"], "false");
+  assert.deepEqual(captions.unclearLineIds(), ["jim-1"]);
+});
+
+test("the Unclear button stops marking at the cap", async (t) => {
+  const { captions, button } = await setupUnclear(t);
+
+  for (let turn = 1; turn <= MAX_UNCLEAR_LINES; turn++) {
+    captions.updateCaptions("interviewer", `Line ${turn}.`, `jim-${turn}`, {
+      final: true,
+    });
+    button.click();
+  }
+  assert.equal(captions.unclearLineIds().length, MAX_UNCLEAR_LINES);
+
+  captions.updateCaptions("interviewer", "One more line.", "jim-extra", {
+    final: true,
+  });
+  assert.equal(button.attributes["aria-disabled"], "true");
+  button.click();
+  assert.equal(captions.unclearLineIds().length, MAX_UNCLEAR_LINES);
+  assert.ok(!captions.unclearLineIds().includes("jim-extra"));
+});
+
+function focusOn(button, nodes, editor = {}) {
+  const document = { activeElement: button };
+  button.ownerDocument = document;
+  const target = (name, options = {}) => ({
+    isConnected: true,
+    disabled: false,
+    ...options,
+    focus() {
+      document.activeElement = nodes[name];
+    },
+  });
+  nodes.editor = target("editor", editor);
+  nodes.board = target("board");
+  return document;
+}
+
+test("candidate speech moves focus off the Unclear button it hides", async (t) => {
+  const { captions, button, nodes } = await setupUnclear(t);
+  const document = focusOn(button, nodes);
+
+  captions.updateCaptions("interviewer", "Use a hash map.", "jim-1", {
+    final: true,
+  });
+  button.click();
+  assert.equal(document.activeElement, button);
+
+  captions.updateCaptions("you", "Okay.", "you-1");
+  assert.equal(button.hidden, true);
+  assert.equal(document.activeElement, nodes.editor);
+});
+
+test("the cap leaves focus on the Unclear button it marks unavailable", async (t) => {
+  const { captions, button, nodes } = await setupUnclear(t);
+  const document = focusOn(button, nodes);
+
+  for (let turn = 1; turn <= MAX_UNCLEAR_LINES; turn++) {
+    captions.updateCaptions("interviewer", `Line ${turn}.`, `jim-${turn}`, {
+      final: true,
+    });
+    button.click();
+  }
+  assert.equal(document.activeElement, button);
+
+  captions.updateCaptions("interviewer", "One more line.", "jim-extra", {
+    final: true,
+  });
+  assert.equal(button.attributes["aria-disabled"], "true");
+  assert.equal(document.activeElement, button);
+});
+
+test("the idle timeout moves focus off the Unclear button it hides", async (t) => {
+  const { captions, button, nodes } = await setupUnclear(t);
+  const document = focusOn(button, nodes);
+
+  // A Jim turn that never turns final keeps the idle timeout armed.
+  captions.updateCaptions("interviewer", "Go on.", "jim-1");
+  t.mock.timers.tick(12000);
+  assert.equal(nodes.captionsBar.hidden, true);
+  assert.equal(document.activeElement, nodes.editor);
+});
+
+test("a code edit moves focus off the Unclear button it hides", async (t) => {
+  const { captions, button, nodes } = await setupUnclear(t);
+  const document = focusOn(button, nodes);
+
+  captions.updateCaptions("interviewer", "Use a hash map.", "jim-1", {
+    final: true,
+  });
+  t.mock.timers.tick(1000);
+  captions.dismissCaptions();
+  assert.equal(nodes.captionsBar.hidden, true);
+  assert.equal(document.activeElement, nodes.editor);
+});
+
+for (const [name, editor] of [
+  ["disabled", { disabled: true }],
+  ["removed", { isConnected: false }],
+]) {
+  test(`focus skips a ${name} editor for the board`, async (t) => {
+    const { captions, button, nodes } = await setupUnclear(t);
+    const document = focusOn(button, nodes, editor);
+
+    captions.updateCaptions("interviewer", "Go on.", "jim-1", { final: true });
+    captions.updateCaptions("you", "Okay.", "you-1");
+    assert.equal(document.activeElement, nodes.board);
+  });
+}
+
+test("a mouse click on Unclear hands focus back to the editor", async (t) => {
+  const { captions, button, nodes } = await setupUnclear(t);
+  const document = focusOn(button, nodes);
+
+  captions.updateCaptions("interviewer", "Go on.", "jim-1", { final: true });
+  button.click({ detail: 1 });
+  assert.equal(button.attributes["aria-pressed"], "true");
+  assert.equal(document.activeElement, nodes.editor);
+});
+
+test("Space or Enter on Unclear keeps focus on the button", async (t) => {
+  const { captions, button, nodes } = await setupUnclear(t);
+  const document = focusOn(button, nodes);
+
+  captions.updateCaptions("interviewer", "Go on.", "jim-1", { final: true });
+  button.click({ detail: 0 });
+  assert.equal(button.attributes["aria-pressed"], "true");
+  assert.equal(document.activeElement, button);
+});

tests/browser/interview-lifecycle.test.js

@@ -5,6 +5,7 @@ import {
   shouldWarnBeforeUnload,
 } from "../../web/before-unload.js";
 import { reportIsPersisted } from "../../web/history.js";
+import { withUnclearLines } from "../../web/lib.js";
 import { functionBody, read } from "./source.js";
 
 function beforeUnloadEvent(target) {
@@ -269,6 +270,8 @@ test("guest reports are not persisted across sessions", async () => {
     "saveReportHistory",
     "reportIsPersisted",
     "updateBeforeUnloadGuard",
+    "unclearLines",
+    "withUnclearLines",
     `let saveGeneration = 0;\n${body}\n}\nreturn saveHistory;`,
   )(
     state,
@@ -282,6 +285,8 @@ test("guest reports are not persisted across sessions", async () => {
     saveReportHistory,
     reportIsPersisted,
     updateBeforeUnloadGuard,
+    () => [],
+    withUnclearLines,
   );
 
   const result = await saveHistory({ summary: "guest report" });
@@ -326,6 +331,8 @@ test("report is saved locally when session state is unavailable", async () => {
     "saveReportHistory",
     "reportIsPersisted",
     "updateBeforeUnloadGuard",
+    "unclearLines",
+    "withUnclearLines",
     `let saveGeneration = 0;\n${body}\n}\nreturn saveHistory;`,
   )(
     state,
@@ -338,6 +345,8 @@ test("report is saved locally when session state is unavailable", async () => {
     saveReportHistory,
     () => true,
     updateBeforeUnloadGuard,
+    () => [],
+    withUnclearLines,
   );
 
   const result = await saveHistory({ summary: "temporary report" });
@@ -379,6 +388,8 @@ test("only the newest overlapping report save can release the warning", async ()
     "saveReportHistory",
     "reportIsPersisted",
     "updateBeforeUnloadGuard",
+    "unclearLines",
+    "withUnclearLines",
     `let saveGeneration = 0;\n${body}\n}\nreturn saveHistory;`,
   )(
     state,
@@ -392,6 +403,8 @@ test("only the newest overlapping report save can release the warning", async ()
     saveReportHistory,
     reportIsPersisted,
     updateBeforeUnloadGuard,
+    () => [],
+    withUnclearLines,
   );
 
   const provisional = saveHistory({ summary: "provisional" });

tests/browser/lib.test.js

@@ -14,6 +14,9 @@ import {
 
 import {
   ACTIVE_CONTRACT,
+  MAX_REPORT_BODY_BYTES,
+  unclearLinesOf,
+  withUnclearLines,
   boardOpBatches,
   surfaceLabel,
   boardStreamOptions,
@@ -3713,3 +3716,50 @@ test("interviewer provenance survives report migration and storage without inven
     128,
   );
 });
+
+test("unclear lines are clipped to 600 UTF-8 bytes with an ellipsis", () => {
+  const bytes = (text) => new TextEncoder().encode(text).length;
+  const exact = "x".repeat(600);
+  const [ascii, cjk, whole, short] = unclearLinesOf([
+    "x".repeat(5000),
+    "\u6e2c".repeat(1000),
+    exact,
+    "Go on.",
+  ]);
+  for (const clipped of [ascii, cjk]) {
+    assert.ok(bytes(clipped) <= 600);
+    assert.ok(bytes(clipped) > 590);
+    assert.ok(clipped.endsWith("\u2026"));
+  }
+  assert.equal(whole, exact);
+  assert.equal(short, "Go on.");
+});
+
+test("marks are dropped before they push the report body past the limit", () => {
+  const lines = Array.from({ length: 10 }, () => "y".repeat(600));
+  const small = { id: "a", report: { summary: "ok" } };
+  assert.deepEqual(withUnclearLines(small, lines).unclearLines, lines);
+  assert.deepEqual(withUnclearLines(small, []), small);
+
+  const size = (value) =>
+    new TextEncoder().encode(JSON.stringify(value)).length;
+  const room =
+    MAX_REPORT_BODY_BYTES - size({ id: "a", report: { summary: "" } });
+  const large = { id: "a", report: { summary: "z".repeat(room - 2000) } };
+  const trimmed = withUnclearLines(large, lines);
+  assert.ok(trimmed.unclearLines.length > 0);
+  assert.ok(trimmed.unclearLines.length < lines.length);
+  assert.ok(size(trimmed) <= MAX_REPORT_BODY_BYTES);
+
+  const full = { id: "a", report: { summary: "z".repeat(room) } };
+  assert.equal("unclearLines" in withUnclearLines(full, lines), false);
+});
+
+test("the report body limit matches the server's", () => {
+  assert.match(
+    readFileSync(new URL("../../src/web/mod.rs", import.meta.url), "utf8"),
+    new RegExp(
+      `MAX_REPORT_BYTES: usize = ${MAX_REPORT_BODY_BYTES / 1024} \\* 1024;`,
+    ),
+  );
+});

tests/browser/progress.test.js

@@ -795,3 +795,37 @@ test("retry mode metadata falls back to the original report and defaults safely"
   assert.equal(invalid.interviewLoop, "coding_behavioral");
   assert.equal(invalid.interviewMode, "coding");
 });
+test("an entry at the unclear-line cap keeps every marked line", () => {
+  const lines = Array.from({ length: 10 }, (_, index) => `Line ${index + 1}.`);
+  const attempt = normalizeProgressEntry(
+    entry("cap", "2026-01-02T00:00:00Z", 70, { unclearLines: lines }),
+  );
+  assert.deepEqual(attempt.unclearLines, lines);
+});
+
+test("unclearLines is ignored unless it is an array of strings", () => {
+  for (const unclearLines of [
+    undefined,
+    null,
+    "Line 1.",
+    42,
+    { 0: "Line 1." },
+    ["Line 1.", 2],
+    ["Line 1.", null],
+  ]) {
+    const attempt = normalizeProgressEntry(
+      entry("bad", "2026-01-02T00:00:00Z", 70, { unclearLines }),
+    );
+    assert.deepEqual(attempt.unclearLines, [], String(unclearLines));
+  }
+});
+test("unclearLines past the cap or too long is bounded on read", () => {
+  const lines = Array.from({ length: 12 }, (_, index) => `Line ${index + 1}.`);
+  lines[0] = "x".repeat(5000);
+  const attempt = normalizeProgressEntry(
+    entry("over", "2026-01-02T00:00:00Z", 70, { unclearLines: lines }),
+  );
+  assert.equal(attempt.unclearLines.length, 10);
+  assert.ok(attempt.unclearLines[0].length < 5000);
+  assert.deepEqual(attempt.unclearLines.slice(1), lines.slice(1, 10));
+});