@jabworks/condux 0.13.2 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/plan-review/references/annotate-server.js

@@ -172,6 +172,24 @@ function gitRoot() {
   }
 }
 
+// Write atomically. A plain writeFileSync is open(O_CREAT|O_TRUNC) then write()
+// — two syscalls — so any reader polling for the file can win the gap and see a
+// created, still-empty file. Writing a sibling temp and rename()-ing it into
+// place is atomic on POSIX: readers see either the old file or the complete new
+// one, never a truncated one. Same directory so the rename never crosses a
+// filesystem. If rename is unavailable (some Windows AV/lock cases), fall back
+// to the direct write rather than losing the feedback.
+function writeFileAtomic(file, data) {
+  const tmp = file + '.' + process.pid + '.tmp';
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try { fs.rmSync(tmp, { force: true }); } catch (e2) { /* nothing to clean */ }
+    fs.writeFileSync(file, data);
+  }
+}
+
 function feedbackMarkdown(decision, thread) {
   const lines = ['# Plan Review Feedback', '',
     '- **Decision:** ' + decision,
@@ -262,7 +280,7 @@ function resolveDecision(decision, thread) {
     // browser tab live-reloads when the agent revises the plan on disk. On a
     // terminal decision (Approve/Reject) the review is over, so we exit after the
     // response flushes; on "Request Revisions" we keep serving the next round.
-    fs.writeFileSync(feedbackFile, md);
+    writeFileAtomic(feedbackFile, md);
     const payload = { decision: decision, feedback: md, feedbackFile: feedbackFile };
     if (decisionWaiter) {
       try { decisionWaiter.writeHead(200, { 'Content-Type': 'application/json' }); decisionWaiter.end(JSON.stringify(payload)); } catch (e) { /* client gone */ }
@@ -276,7 +294,7 @@ function resolveDecision(decision, thread) {
       setTimeout(function () { process.exit(0); }, 400);
     }
   } else {
-    fs.writeFileSync(feedbackFile, md);
+    writeFileAtomic(feedbackFile, md);
     log('\n[PLAN-REVIEW FEEDBACK -> ' + feedbackFile + ']\n' + md + '\n');
   }
 }

package/skills/plan-review/references/plan-review-template.html

@@ -476,12 +476,21 @@
          the smaller 0.25rem step now say so explicitly via --radius, which
          already carries that value and is already this file's convention
          (.nav .tabs, .popover, .chip, code, pre, …). */
+      /* Docket #48 / Q16 — three theme states, not two. These tokens are
+         dark-first like the core, so their light values are an override. Written
+         as a bare media query, clicking Dark on a light system flipped every core
+         token and left the highlight cream, because the media query still
+         matched. Written the way scripts/tokens/core.css:84-85,130 writes it:
+         the system-light block excludes an explicit dark stamp, and an explicit
+         light block beats a dark OS. */
       :root {
         --hl: rgba(255, 202, 22, 0.30); --hl-active: rgba(255, 202, 22, 0.55);
       }
       @media (prefers-color-scheme: light) {
-        :root { --hl: rgba(234, 179, 8, 0.42); --hl-active: rgba(202, 138, 4, 0.62); }
+        :root:not([data-theme="dark"]) { --hl: rgba(234, 179, 8, 0.42); --hl-active: rgba(202, 138, 4, 0.62); }
       }
+      :root[data-theme="light"] { --hl: rgba(234, 179, 8, 0.42); --hl-active: rgba(202, 138, 4, 0.62); }
+      :root[data-theme="dark"] { --hl: rgba(255, 202, 22, 0.30); --hl-active: rgba(255, 202, 22, 0.55); }
       * { box-sizing: border-box; }
       html, body { height: 100%; }
       /* .kit-error sets display:flex unconditionally; an author rule beats the
@@ -493,9 +502,16 @@
          one legitimately 2-D layout in this file; everything else here is a
          one-dimensional row or column and stays flex. */
       body { margin: 0; background: var(--background); color: var(--foreground); font-family: var(--sans); font-size: var(--text-sm); line-height: var(--leading-normal); font-variant-numeric: tabular-nums; display: grid; grid-template-rows: 1fr auto; height: 100dvh; }
-      .app { display: grid; grid-template-columns: 248px minmax(0, 1fr) 372px; min-height: 0; }
+      /* D10 — the document takes the width the two lists were spending. Every
+         column rule is scoped ABOVE the stacking breakpoint on purpose: an
+         unscoped `grid-template-columns` outranks the 860px and 1100px rules by
+         source order, and the three-column grid survives into a phone viewport.
+         Measured at 640px while building D10: `.main` collapsed to 88px and the
+         340px popover ran off the right edge of the screen. */
+      .app { display: grid; grid-template-columns: 236px minmax(0, 1fr) 330px; min-height: 0; }
+      .app > * { min-width: 0; }   /* Q14 — a bare 1fr column floors at min-content */
       @media (max-width: 1100px) {
-        .app { grid-template-columns: 208px minmax(0, 1fr) 320px; }
+        .app { grid-template-columns: 208px minmax(0, 1fr) 300px; }
       }
       @media (max-width: 860px) {
         .app { grid-template-columns: 1fr; grid-template-rows: auto 1fr auto; max-height: none; }
@@ -537,8 +553,12 @@
       .badge-warning { background: var(--warning-muted); color: var(--warning); border-color: var(--warning-border); }
       .badge-soft { background: var(--primary-muted); color: var(--primary-text); }
 
-      /* Left: navigation — Contents (docs + headings) | Files (paths touched) */
-      .nav { border-right: 1px solid var(--border); background: var(--card); overflow-y: auto; padding: 18px 14px 40px; }
+      /* Left: navigation — Contents (docs + headings) | Files (paths touched).
+         D10 — a table of contents rather than a menu: no card ground, no active
+         pill, depth as padding. Note `.nav a` is display:flex, so a negative
+         text-indent does not produce a hanging indent here — it shifts the flex
+         container's first line and clips the label against the row. */
+      .nav { border-right: 1px solid var(--border); background: var(--background); overflow-y: auto; padding: 22px 16px 40px; }
       .nav .kit-theme { margin: 0 0 12px; }
       .nav .tabs { display: flex; margin: 0 0 12px; border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; }
       .nav .tab { flex: 1; font: 500 var(--text-2xs) var(--sans); letter-spacing: .08em; text-transform: uppercase; padding: 6px 4px;
@@ -547,16 +567,16 @@
       .nav .tab:hover { color: var(--foreground); }
       .nav .tab.active { background: var(--accent); color: var(--foreground); }
       .nav a.doc { font-weight: 600; color: var(--foreground); }
-      .nav a.doc.active { border-left-color: var(--primary); background: var(--accent); }
+      .nav a.doc.active { color: var(--foreground); background: transparent; }
       .nav a.file .t { font-family: var(--mono); font-size: var(--text-xs); }
       .nav .none { color: var(--subtle); font-size: var(--text-xs); padding: 4px 6px; }
       code.mention-flash { outline: 2px solid var(--warning); outline-offset: 1px; }
       .nav .label, .chat .label { font-size: var(--text-2xs); letter-spacing: 0.08em; text-transform: uppercase; color: var(--subtle); margin: 0 0 12px; padding: 0 6px; }
-      .nav a { display: flex; align-items: center; gap: 6px; color: var(--muted-foreground); text-decoration: none; padding: 4px 6px; border-radius: 4px; border-left: 2px solid transparent; }
+      .nav a { display: flex; align-items: center; gap: 6px; color: var(--muted-foreground); text-decoration: none; padding: 3px 2px; border-radius: 0; border-left: none; }
       .nav a span.t { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; flex: 1; }
-      .nav a:hover { background: var(--accent); color: var(--foreground); }
-      .nav a.active { color: var(--foreground); border-left-color: var(--primary); background: var(--accent); }
-      .nav a.lvl2 { padding-left: 16px; } .nav a.lvl3 { padding-left: 28px; font-size: var(--text-xs); color: var(--subtle); }
+      .nav a:hover { color: var(--foreground); }
+      .nav a.active { color: var(--foreground); font-weight: 600; background: transparent; }
+      .nav a.lvl2 { padding-left: 14px; } .nav a.lvl3 { padding-left: 26px; font-size: var(--text-xs); color: var(--subtle); }
 
       /* Directory mode: doc-site tree — folder rows fold, filter narrows, the
          active doc alone carries its headings. All of it DIRMODE-gated. */
@@ -566,14 +586,14 @@
       .nav .tree-filter input:focus { border-color: var(--ring); }
       .nav a.folder { font-weight: 600; color: var(--muted-foreground); }
       .nav a.folder .arrow { flex: none; width: 12px; color: var(--subtle); font-size: var(--text-2xs); }
-      .crumbs { display: none; max-width: 760px; margin: 0 auto 18px; font: var(--text-xs) var(--mono); color: var(--subtle);
+      .crumbs { display: none; max-width: 720px; margin: 0 auto 18px; font: var(--text-xs) var(--mono); color: var(--subtle);
         white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
       .crumbs .seg { color: var(--muted-foreground); }
       .crumbs a.seg { color: var(--muted-foreground); text-decoration: none; cursor: pointer; }
       .crumbs a.seg:hover { color: var(--foreground); text-decoration: underline; }
       .crumbs .sep { margin: 0 6px; color: var(--subtle); }
       .crumbs .cur { color: var(--foreground); }
-      .pnav { display: none; max-width: 760px; margin: 32px auto 0; padding-top: 14px; border-top: 1px solid var(--border);
+      .pnav { display: none; max-width: 720px; margin: 32px auto 0; padding-top: 14px; border-top: 1px solid var(--border);
         justify-content: space-between; gap: 12px; }
       .pnav a { display: inline-flex; align-items: center; gap: 6px; max-width: 48%; color: var(--muted-foreground);
         text-decoration: none; font-size: var(--text-sm); padding: 6px 10px; border: 1px solid var(--border); border-radius: var(--radius);
@@ -581,23 +601,23 @@
       .pnav a:hover { background: var(--accent); color: var(--foreground); }
       .pnav .spacer { flex: 1; }
 
-      /* Center: plan */
-      .main { overflow-y: auto; padding: 28px 44px 120px; position: relative;
-        background-image:
-          linear-gradient(to right, color-mix(in oklab, var(--foreground) 3%, transparent) 1px, transparent 1px),
-          linear-gradient(to bottom, color-mix(in oklab, var(--foreground) 3%, transparent) 1px, transparent 1px);
-        background-size: 32px 32px; }
-      .main .hint { color: var(--subtle); margin: 0 auto 24px; font-size: var(--text-xs); max-width: 760px; }
-      .doc { max-width: 760px; margin: 0 auto; line-height: var(--leading-relaxed); }
+      /* Center: plan. `position: relative` and `overflow-y: auto` are load-bearing
+         and must both stay: #popover is absolutely positioned against this box,
+         and selDoc stores coordinates relative to it plus its scrollTop. Moving
+         the scroll to body, or wrapping #plan in its own scroller, silently
+         breaks every annotation anchor. */
+      .main { overflow-y: auto; padding: 40px 44px 140px; position: relative; }
+      .main .hint { color: var(--subtle); margin: 0 auto 24px; font-size: var(--text-xs); max-width: 720px; }
+      .doc { max-width: 720px; margin: 0 auto; line-height: var(--leading-relaxed); counter-reset: hl; }
 
       /* Revision diff — on a revised plan, show what changed instead of a silent swap. */
-      .revbar { display: none; align-items: center; gap: 10px; max-width: 760px; margin: 0 auto 20px;
+      .revbar { display: none; align-items: center; gap: 10px; max-width: 720px; margin: 0 auto 20px;
         padding: 9px 12px; border: 1px solid var(--warning-border); background: var(--warning-muted); border-radius: var(--radius); }
       .revbar.show { display: flex; }
       .revbar .rb-text { color: var(--warning); font: 600 var(--text-xs) var(--sans); }
       .revbar .rb-stat { color: var(--muted-foreground); font-size: var(--text-xs); }
       .revbar .rb-actions { margin-left: auto; display: flex; gap: 6px; }
-      .diffwrap { display: none; max-width: 760px; margin: 0 auto; }
+      .diffwrap { display: none; max-width: 720px; margin: 0 auto; }
       .diffwrap.show { display: block; }
       .diffview { background: var(--muted); border: 1px solid var(--border); border-radius: var(--radius);
         padding: 8px 0; overflow-x: auto; font: var(--text-xs)/var(--leading-normal) var(--mono); }
@@ -609,11 +629,24 @@
       .diffline.del { background: var(--destructive-muted); color: var(--destructive); }
       .diffline.del .g { color: var(--destructive); }
       .diffline.fold { justify-content: center; color: var(--subtle); font-style: italic; padding: 3px 12px; }
+      /* D10 — a typographic spine. Hierarchy is space and rule, not boxes: h1
+         closes with a rule, h2 opens a section against a hairline, h3 hangs off
+         a short dash. This is what makes a long plan skimmable without folding
+         it — folds are ruled out on this surface (live Ranges and mark.hl nodes
+         have no client rects inside a collapsed <details>). */
       h1, h2, h3, h4, h5, h6 { line-height: var(--leading-snug); margin: 1.5em 0 0.6em; scroll-margin-top: 24px; }
-      h1 { font-size: var(--text-xl); } h2 { font-size: var(--text-md); } h3 { font-size: var(--text-base); color: var(--muted-foreground); }
+      h1 { font-size: var(--text-2xl); letter-spacing: -0.015em; margin: 0 0 0.2em; padding-bottom: 0.5em; border-bottom: 1px solid var(--border); }
+      h2 { font-size: var(--text-lg); letter-spacing: -0.01em; margin: 2.4em 0 0.7em; padding-top: 0.9em; border-top: 1px solid var(--border); }
+      h3 { font-size: var(--text-base); color: var(--foreground); margin: 1.9em 0 0.5em; }
+      h3::before { content: ''; display: inline-block; width: 14px; height: 1px; vertical-align: middle; margin-right: 10px; background: var(--subtle); }
       h4 { font-size: var(--text-sm); } h5, h6 { font-size: var(--text-xs); color: var(--muted-foreground); }
+      .doc > *:first-child, .docpane > *:first-child { margin-top: 0; }
       p { margin: 0.6em 0; }
       ul, ol { margin: 0.6em 0; padding-left: 22px; } li { margin: 0.25em 0; }
+      /* Q15 — capping measure on <p> alone misses the worst line, and a plan is
+         mostly list items. Table cells keep their column. */
+      .doc p, .doc li { max-width: 68ch; }
+      .doc td p, .doc td li, .doc th p { max-width: none; }
       li.task { list-style: none; margin-left: -18px; }
       del { color: var(--subtle); }
       a { color: var(--info); }
@@ -622,12 +655,32 @@
       pre code { background: none; border: none; padding: 0; }
       blockquote { margin: 0.6em 0; padding: 2px 14px; color: var(--muted-foreground); border-left: 3px solid var(--primary); }
       hr { border: none; border-top: 1px solid var(--border); margin: 1.6em 0; }
+      /* D10 — h2 now opens a section against its own rule, which makes a
+         preceding `---` a second divider saying the same thing. draft-plan's
+         canonical template puts `---` immediately before every task card, so
+         this is the shape of nearly every plan this surface renders: measured
+         9 doubled rules in one 9-task plan. Each block is wrapped in its own
+         .blk, so `hr + h2` cannot match — the relative selector looks forward
+         to the next block instead. The h2's rule is the spine and stays; the
+         redundant separator goes. */
+      .blk:has(> hr):has(+ .blk h2) { display: none; }
       table { border-collapse: collapse; margin: 0.9em 0; width: 100%; display: block; overflow-x: auto; font-size: var(--text-sm); }
       th, td { border: 1px solid var(--border); padding: 6px 10px; text-align: left; vertical-align: top; }
       th { background: var(--muted); font-weight: 600; }
       tbody tr:nth-child(even) { background: color-mix(in oklch, var(--muted) 40%, transparent); }
       .blk { border-radius: 4px; padding: 1px 8px; margin: 0 -8px; }
-      mark.hl { background: var(--hl); color: inherit; border-radius: 2px; cursor: pointer; padding: 0 1px; }
+      /* D10 — numbered marginalia. The counter increments per highlight in
+         document order and the review column repeats the same ordinal in its
+         gutter, so the two columns read as one artifact. paint() orders the
+         thread by document position to keep the two numberings in agreement —
+         without that they diverge the moment a note is added above an earlier
+         one. The counter is also the only trace of an annotation on paper, since
+         the review column is print-suppressed. */
+      mark.hl { background: var(--hl); color: inherit; border-radius: 2px; cursor: pointer; padding: 0.1em 1px;
+        box-decoration-break: clone; -webkit-box-decoration-break: clone; counter-increment: hl; }
+      mark.hl::after { content: counter(hl); font: 600 var(--text-2xs) var(--mono); color: var(--muted-foreground);
+        vertical-align: super; margin-left: 2px; line-height: 0; }
+      mark.hl:hover { background: var(--hl-active); }
       mark.hl.active { background: var(--hl-active); box-shadow: 0 0 0 1px var(--warning-border); }
 
       /* Floating "comment" button (Button surface) + comment Popover */
@@ -664,20 +717,51 @@
       .popover .ta { min-height: 132px; border: none; border-radius: 0; padding: 8px 10px; } .popover .ta:focus-visible { outline: none; box-shadow: none; }
       .composer .ta { min-height: 52px; }
 
-      /* Right: annotations (Cards) + composer + decisions */
-      .chat { border-left: 1px solid var(--border); background: var(--card); display: flex; flex-direction: column; }
-      .chat .label { padding: 16px 16px 0; margin-bottom: 8px; display: flex; align-items: center; gap: 8px; }
-      .thread { flex: 1; overflow-y: auto; padding: 6px 14px; display: flex; flex-direction: column; gap: 8px; }
+      /* Right: annotations as marginalia + composer + decisions.
+         D10 — the review column recedes so the document can lead. Notes lose
+         their card chrome and are separated by rule alone, each keyed by the
+         same ordinal its highlight carries in the document. */
+      .chat { border-left: 1px solid var(--border); background: var(--background); display: flex; flex-direction: column; }
+      .chat .label { padding: 22px 18px 0; margin-bottom: 4px; display: flex; align-items: center; gap: 8px;
+        font: 600 var(--text-2xs) var(--sans); letter-spacing: .09em; text-transform: uppercase; color: var(--subtle); }
+      .thread { flex: 1; overflow-y: auto; padding: 10px 18px; display: flex; flex-direction: column; gap: 0; counter-reset: note; }
       .thread .empty { color: var(--subtle); padding: 8px 4px; }
-      /* Terminus: Card */
-      .msg { border: 1px solid var(--border); border-radius: var(--radius); padding: 10px 12px; background: var(--card); box-shadow: var(--shadow-sm); cursor: default; }
-      .msg.note { border-color: var(--warning-border); cursor: pointer; }
-      .msg.note.active { box-shadow: 0 0 0 2px var(--warning); }
+      .msg { position: relative; background: transparent; border: none; border-top: 1px solid var(--border);
+        border-left: 2px solid transparent; border-radius: 0; padding: 14px 0 14px 26px; box-shadow: none; cursor: default; }
+      .msg:first-child { border-top: none; }
+      .msg::before { counter-increment: note; content: counter(note); position: absolute; left: 8px; top: 15px;
+        font: 600 var(--text-2xs) var(--mono); color: var(--subtle); }
+      /* A note on another document takes no ordinal — see paint(). The marker
+         says "annotated, elsewhere" without claiming a position in a sequence
+         the reader cannot see. */
+      .msg[data-other-doc]::before { counter-increment: none; content: '·'; }
+      .msg.note { cursor: pointer; }
+      .msg.note.active { background: var(--accent); }
       .msg .meta { display: flex; justify-content: space-between; gap: 8px; margin-bottom: 4px; align-items: center; }
-      .msg .who { color: var(--muted-foreground); font-size: var(--text-2xs); font-weight: 600; text-transform: uppercase; letter-spacing: .07em; } .msg.note .who { color: var(--warning); }
+      .msg .who { color: var(--muted-foreground); font: 600 var(--text-2xs) var(--sans); text-transform: uppercase; letter-spacing: .07em; }
       .msg .del { cursor: pointer; border: none; background: none; color: var(--subtle); font-size: var(--text-2xs); padding: 0 2px; } .msg .del:hover { color: var(--destructive); }
-      .msg .quote { color: var(--muted-foreground); font-size: var(--text-2xs); border-left: 2px solid var(--warning); padding: 1px 8px; margin-bottom: 5px; max-height: 42px; overflow: hidden; }
-      .msg .body { white-space: pre-wrap; word-break: break-word; color: var(--card-foreground); }
+      .msg .quote { color: var(--muted-foreground); font-size: var(--text-2xs); font-style: italic; border-left: 2px solid var(--hl-active); padding: 1px 9px; margin-bottom: 6px; max-height: 42px; overflow: hidden; }
+      .msg .body { white-space: pre-wrap; word-break: break-word; color: var(--foreground); }
+
+      /* Category as colour, carried by the two marks already in the gutter — the
+         ordinal and the label — rather than by a card edge. Lets you count the
+         issues in a full thread without reading it. `data-cat` is set in paint();
+         the category is otherwise only written as TEXT into .who, and CSS cannot
+         select on text content. */
+      /* The five categories are exactly the popover's chips — Comment, Issue,
+         Question, Suggestion, Nitpick — plus "Note", which is what a note gets
+         when no chip was clicked (openToolbar clears pendingCat on every open,
+         so the markup's initial `active` chip is not a default). Comment and
+         Note are deliberately quiet: they are the common case, and colouring
+         them would leave nothing for the categories that carry a decision. */
+      .msg[data-cat="Issue"] { border-left-color: var(--destructive); }
+      .msg[data-cat="Issue"]::before, .msg[data-cat="Issue"] .who { color: var(--destructive); }
+      .msg[data-cat="Question"] { border-left-color: var(--warning); }
+      .msg[data-cat="Question"]::before, .msg[data-cat="Question"] .who { color: var(--warning); }
+      .msg[data-cat="Suggestion"] { border-left-color: var(--primary); }
+      .msg[data-cat="Suggestion"]::before, .msg[data-cat="Suggestion"] .who { color: var(--primary-text); }
+      .msg[data-cat="Nitpick"] { border-left-color: var(--subtle); }
+      .msg[data-cat="Nitpick"]::before, .msg[data-cat="Nitpick"] .who { color: var(--subtle); }
 
       /* Terminus: Separator + composer */
       .composer { border-top: 1px solid var(--border); padding: 12px 14px; }
@@ -709,6 +793,22 @@
       .sent .again { margin-top: 10px; }
       .dot { width: 7px; height: 7px; border-radius: 9999px; background: currentColor; animation: pulse 1.3s ease-in-out infinite; }
       @keyframes pulse { 0%, 100% { opacity: .3; } 50% { opacity: 1; } }
+
+      /* Docket #50 — the shell has to COLLAPSE for print, not just hide its
+         chrome. The kit's print block sets [data-kit-chrome] { display: none },
+         which hides .nav and .chat but leaves their grid TRACKS on .app, so
+         .main auto-placed into the first (248px) track and the plan printed in a
+         ~151px column. .main is also the scroll container, so printed output was
+         clipped to the one screenful scrolled into view — the rest of the plan
+         did not print at all.
+         The measure cap stays: prose set to the full page width is no more
+         readable on paper than on screen. Only the centring margin goes, so the
+         column sits against the page's own margin. */
+      @media print {
+        .app { display: block; }
+        .main { overflow: visible; padding: 0; height: auto; }
+        .doc, .crumbs { margin: 0; }
+      }
     </style>
   </head>
   <body>
@@ -1473,12 +1573,47 @@
       function sendChat(){ const ta=document.getElementById('input'); const text=ta.value.trim(); if(!text)return;
         annotations.push({id:nextId++,kind:'chat',quote:'',text:text,section:''}); ta.value=''; paint(); }
 
+      // The thread renders in DOCUMENT order, not insertion order, because each
+      // highlight carries a CSS counter numbered by document position and the
+      // gutter repeats that ordinal. Left in insertion order the two numberings
+      // disagree the moment a note is added above an earlier one.
+      //
+      // Sort a COPY: `annotations` is the identity store that saveNote pushes to
+      // and the delete handler indexes into with indexOf, so reordering it in
+      // place breaks both. And never reorder the rendered DOM instead — chat
+      // messages have no document position and would be shuffled to the top.
+      function threadOrder(){
+        // Scope the mark lookup to the ACTIVE pane. In DIRMODE every doc's pane
+        // stays in the DOM hidden, so a document-wide query happily matches a
+        // mark in another document's pane and sorts against it.
+        const pane=docState[activeDoc]&&docState[activeDoc].pane;
+        const markOf=function(a){ return pane?pane.querySelector('mark.hl[data-aid="'+a.id+'"]'):null; };
+        // Array.prototype.sort is stable, so a 0 comparison keeps chat messages
+        // — and any note whose mark is missing — in their existing order.
+        return annotations.slice().sort(function(x,y){
+          if(x.kind!=='note'||y.kind!=='note') return 0;
+          const mx=markOf(x), my=markOf(y);
+          if(!mx||!my) return 0;
+          return (mx.compareDocumentPosition(my)&Node.DOCUMENT_POSITION_FOLLOWING)?-1:1;
+        });
+      }
       function paint(){
         const box=document.getElementById('thread'); box.innerHTML='';
         document.getElementById('count').textContent=annotations.length?'('+annotations.length+')':'';
         if(!annotations.length){ box.innerHTML='<div class="empty">No notes yet. Select text to comment, or send a message.</div>'; updateBadges(); updateSummary(); return; }
-        annotations.forEach(function(a){
+        threadOrder().forEach(function(a){
           const m=document.createElement('div'); m.className='msg'+(a.kind==='note'?' note':''); if(a.kind==='note')m.dataset.aid=String(a.id);
+          // The category is otherwise written only as TEXT into .who, and CSS
+          // cannot select on text content — this is what the colour rules key on.
+          m.dataset.cat=(a.kind==='note'?(a.cat||'Note'):'message');
+          // DIRMODE: the thread lists notes from EVERY document, but the in-document
+          // ordinal counts only the visible pane — marks inside a display:none pane
+          // do not increment a CSS counter. Numbering every row would therefore
+          // label a note "3" in the gutter whose highlight reads "1" in the
+          // document, which is exactly the divergence the numbering exists to
+          // remove. Rows belonging to another document are flagged so they take no
+          // ordinal, leaving both sequences running 1..m over the same set.
+          if(a.kind==='note'&&a.doc&&a.doc!==activeDoc) m.dataset.otherDoc='1';
           const meta=document.createElement('div'); meta.className='meta';
           const who=document.createElement('span'); who.className='who'; who.textContent=a.kind==='note'?(a.cat||'Note'):'message';
           const del=document.createElement('button'); del.className='del'; del.textContent='×';
@@ -1552,7 +1687,12 @@
         if(submitting) return; submitting=true;
         document.querySelectorAll('.dbar button').forEach(function(b){b.disabled=true;});
         try{
-          const r=await fetch('/api/feedback',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({decision:decision,thread:annotations})});
+          // Send the thread in the SAME order the reviewer saw it. The rendered
+          // thread is ordered by document position and each note is numbered in
+          // the gutter; posting the raw insertion-order array would hand the
+          // agent a different numbering than the one on screen, so "note 1" in a
+          // conversation would mean two different notes.
+          const r=await fetch('/api/feedback',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({decision:decision,thread:threadOrder()})});
           if(!r.ok) throw new Error('status '+r.status);
           hideApiError();
           decisionSent=true;    // a terminal decision makes the server exit —