@kontourai/survey 3.0.0 → 5.0.0

package/dist/src/canonical-reviewed-trust-input.js

@@ -1,6 +1,6 @@
 import { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 import { canonicalJson } from "./review-workbench/canonical.js";
-import { workbenchDecisionDefinitions } from "./review-workbench/review-queue-session.js";
+import { decisionSelectsNoCandidate, workbenchDecisionDefinitions } from "./review-workbench/review-queue-session.js";
 /**
  * Projects server-applied review records into the complete SurveyInput consumed
  * by buildSurveyTrustBundle. The ReviewItem and ReviewWorkbenchResult are the
@@ -33,15 +33,24 @@ export function buildCanonicalReviewedTrustInput(options) {
             throw new Error(`ReviewItem ${item.metadata.name} has no canonical server-applied result.`);
         }
         assertCanonicalResult(item, result);
+        // Reject-all or could-not-confirm on a conflict selects no candidate: the
+        // set, the review outcome and the claim then name none of its values.
+        const selectsNone = decisionSelectsNoCandidate(item, result.decision);
+        const rejectsAll = selectsNone && result.decision === "reject-proposed";
+        const rejectedRole = workbenchDecisionDefinitions[result.decision].candidateRole;
+        const rejectAllReason = result.rationale?.trim() || "Every proposed value for this claim was rejected.";
         const candidates = item.spec.candidates.map((candidate) => {
-            const records = projectCandidate(item, candidate);
+            const records = projectCandidate(item, rejectsAll && candidate.role === rejectedRole
+                ? { ...candidate, rejectionReason: candidate.rejectionReason ?? rejectAllReason }
+                : candidate);
             addConsistent(rawSources, records.rawSource, "raw source");
             addConsistent(extractions, records.extraction, "extraction");
             return records.candidate;
         });
-        const selected = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
-        const selectedRecordId = selected.projection?.candidateId ?? selected.id;
-        const candidateSetId = selected.projection?.candidateSetId
+        const selected = selectsNone ? undefined : item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
+        const selectedRecordId = selected ? selected.projection?.candidateId ?? selected.id : undefined;
+        // Every candidate carries the same candidate-set id (checked below).
+        const candidateSetId = (selected ?? item.spec.candidates[0])?.projection?.candidateSetId
             ?? item.spec.projection?.candidateSetId
             ?? `${item.metadata.name}.candidates`;
         if (candidates.some((candidate) => candidate.metadata?.candidateSetId !== candidateSetId)) {
@@ -56,10 +65,10 @@ export function buildCanonicalReviewedTrustInput(options) {
                     ? { metadata: Object.fromEntries(Object.entries(metadata).filter(([key]) => key !== "candidateSetId")) }
                     : {}),
             })),
-            selectedCandidateId: selectedRecordId,
+            ...(selectedRecordId !== undefined ? { selectedCandidateId: selectedRecordId } : {}),
             status: result.decision === "could-not-confirm"
                 ? (item.spec.candidateSetStatus ?? "needs-review")
-                : "resolved",
+                : rejectsAll ? "rejected" : "resolved",
             ...(result.rationale ?? item.spec.rationale
                 ? { rationale: result.rationale ?? item.spec.rationale }
                 : {}),
@@ -67,12 +76,12 @@ export function buildCanonicalReviewedTrustInput(options) {
         addConsistent(candidateSets, candidateSet, "candidate set");
         const decision = result.reviewDecision.spec;
         const reviewOutcomeId = decision.projection?.reviewOutcomeId
-            ?? selected.projection?.reviewOutcomeId
+            ?? (selected ?? item.spec).projection?.reviewOutcomeId
             ?? `${item.metadata.name}.${result.decision}.review-outcome`;
         const reviewOutcome = {
             id: reviewOutcomeId,
             candidateSetId,
-            candidateId: selectedRecordId,
+            ...(selectedRecordId !== undefined ? { candidateId: selectedRecordId } : {}),
             status: result.status,
             ...(decision.resolution ? { resolution: decision.resolution } : {}),
             ...(decision.resolutionReason ? { resolutionReason: decision.resolutionReason } : {}),
@@ -90,34 +99,42 @@ export function buildCanonicalReviewedTrustInput(options) {
             },
         };
         addConsistent(reviewOutcomes, reviewOutcome, "review outcome");
-        const hint = selected.claimTarget;
+        // Every candidate names the same claim target (checked by assertCanonicalResult).
+        const hint = (selected ?? item.spec.candidates[0]).claimTarget;
         assertSingleProjectionId("claim", item.metadata.name, [
             decision.projection?.claimId,
             item.spec.projection?.claimId,
             ...item.spec.candidates.flatMap((candidate) => [candidate.projection?.claimId, candidate.claimTarget.claimId]),
         ]);
         const claimId = decision.projection?.claimId
-            ?? selected.projection?.claimId
+            ?? selected?.projection?.claimId
             ?? item.spec.projection?.claimId
             ?? hint.claimId
             ?? `${item.metadata.name}.claim`;
         const claim = {
             id: claimId,
             candidateSetId,
-            candidateId: selectedRecordId,
+            ...(selectedRecordId !== undefined ? { candidateId: selectedRecordId } : {}),
             subjectType: hint.subjectType,
             subjectId: hint.subjectId,
             facet: hint.facet,
             claimType: hint.claimType,
             fieldOrBehavior: hint.fieldOrBehavior,
-            value: result.effectiveValue,
-            status: result.status,
+            // Surface requires a claim value; a claim that selects none of its
+            // candidates carries null, and buildSurveyTrustBundle lists every value.
+            value: selectsNone ? null : result.effectiveValue,
+            // Could-not-confirm keeps the pre-review posture, and a conflicting or
+            // escalated candidate set is disputed before any review (see
+            // docs/decisions/could-not-confirm.md), never merely proposed.
+            status: result.decision === "could-not-confirm" && (candidateSet.status === "conflict" || candidateSet.status === "escalated")
+                ? "disputed"
+                : result.status,
             impactLevel: hint.impactLevel,
             updatedAt: decision.reviewedAt ?? options.generatedAt,
             ...(hint.evidenceType ? { evidenceType: hint.evidenceType } : {}),
             ...(hint.evidenceMethod ? { evidenceMethod: hint.evidenceMethod } : {}),
             ...(hint.derivedFrom ? { derivedFrom: [...hint.derivedFrom] } : {}),
-            collectedBy: hint.collectedBy ?? selected.extraction.extractor ?? options.source,
+            collectedBy: hint.collectedBy ?? sharedExtractor(selected ? [selected] : item.spec.candidates) ?? options.source,
             ...(decision.actor?.id ? { actor: decision.actor.id } : {}),
         };
         addConsistent(claims, claim, "claim target");
@@ -137,24 +154,38 @@ export function buildCanonicalReviewedTrustInput(options) {
     };
 }
 function assertCanonicalResult(item, result) {
-    const selected = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
-    if (!selected) {
-        throw new Error(`Review result ${result.reviewItemName} selects an unknown candidate.`);
-    }
-    if (canonicalJson(selected) !== canonicalJson(result.selectedCandidate)) {
-        throw new Error(`Review result ${result.reviewItemName} selected candidate does not match its canonical ReviewItem.`);
-    }
-    const unselected = item.spec.candidates.filter((candidate) => candidate.id !== selected.id);
-    if (canonicalJson(unselected) !== canonicalJson(result.unselectedCandidates)) {
-        throw new Error(`Review result ${result.reviewItemName} unselected candidates do not match its canonical ReviewItem.`);
+    const selectsNone = decisionSelectsNoCandidate(item, result.decision);
+    let selected;
+    if (selectsNone) {
+        if (result.selectedCandidate !== undefined || result.selectedCandidateId !== undefined || result.selectedCandidateRole !== undefined
+            || result.selectedValue !== undefined || result.selectedDisplayValue !== undefined
+            || result.effectiveValue !== undefined || result.effectiveDisplayValue !== undefined || result.editedValue !== undefined) {
+            throw new Error(`Review result ${result.reviewItemName} names a selected value, but its ${result.decision} decision selects no candidate.`);
+        }
+        if (canonicalJson(item.spec.candidates) !== canonicalJson(result.unselectedCandidates)) {
+            throw new Error(`Review result ${result.reviewItemName} unselected candidates do not match its canonical ReviewItem.`);
+        }
     }
-    if (result.selectedCandidateRole !== selected.role || canonicalJson(result.selectedValue) !== canonicalJson(selected.value)) {
-        throw new Error(`Review result ${result.reviewItemName} selected identity does not match its canonical ReviewItem.`);
+    else {
+        selected = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
+        if (!selected) {
+            throw new Error(`Review result ${result.reviewItemName} selects an unknown candidate.`);
+        }
+        if (canonicalJson(selected) !== canonicalJson(result.selectedCandidate)) {
+            throw new Error(`Review result ${result.reviewItemName} selected candidate does not match its canonical ReviewItem.`);
+        }
+        const unselected = item.spec.candidates.filter((candidate) => candidate.id !== selected.id);
+        if (canonicalJson(unselected) !== canonicalJson(result.unselectedCandidates)) {
+            throw new Error(`Review result ${result.reviewItemName} unselected candidates do not match its canonical ReviewItem.`);
+        }
+        if (result.selectedCandidateRole !== selected.role || canonicalJson(result.selectedValue) !== canonicalJson(selected.value)) {
+            throw new Error(`Review result ${result.reviewItemName} selected identity does not match its canonical ReviewItem.`);
+        }
     }
     const decision = result.reviewDecision.spec;
     const definition = workbenchDecisionDefinitions[result.decision];
     if (decision.reviewItemName !== item.metadata.name
-        || decision.candidateId !== result.selectedCandidateId
+        || decision.candidateId !== selected?.id
         || decision.status !== result.status
         || decision.status !== definition.status
         || decision.rationale !== result.rationale
@@ -164,14 +195,17 @@ function assertCanonicalResult(item, result) {
     if ((result.decision === "could-not-confirm") !== (decision.resolution === "could_not_confirm")) {
         throw new Error(`Review result ${result.reviewItemName} contradicts its canonical review resolution.`);
     }
-    const expectedEffective = result.editedValue !== undefined && result.decision === "accept-proposed"
-        ? result.editedValue
-        : selected.value;
-    if (canonicalJson(expectedEffective) !== canonicalJson(result.effectiveValue)) {
-        throw new Error(`Review result ${result.reviewItemName} effective value is not canonical.`);
+    if (selected) {
+        const expectedEffective = result.editedValue !== undefined && result.decision === "accept-proposed"
+            ? result.editedValue
+            : selected.value;
+        if (canonicalJson(expectedEffective) !== canonicalJson(result.effectiveValue)) {
+            throw new Error(`Review result ${result.reviewItemName} effective value is not canonical.`);
+        }
     }
+    const reference = selected ?? item.spec.candidates[0];
     for (const candidate of item.spec.candidates) {
-        if (canonicalJson(claimTargetIdentity(candidate.claimTarget)) !== canonicalJson(claimTargetIdentity(selected.claimTarget))) {
+        if (canonicalJson(claimTargetIdentity(candidate.claimTarget)) !== canonicalJson(claimTargetIdentity(reference.claimTarget))) {
             throw new Error(`ReviewItem ${item.metadata.name} candidates carry conflicting claim targets.`);
         }
     }
@@ -263,3 +297,8 @@ function assertSingleProjectionId(label, itemName, values) {
         throw new Error(`ReviewItem ${itemName} carries conflicting ${label} projection ids.`);
     }
 }
+/** The extractor every candidate shares, or undefined when they differ. */
+function sharedExtractor(candidates) {
+    const extractors = new Set(candidates.map((candidate) => candidate.extraction.extractor));
+    return extractors.size === 1 ? [...extractors][0] : undefined;
+}

package/dist/src/console/review-console-server.d.ts

@@ -5,7 +5,9 @@
  * Routes:
  *   GET  /              HTML shell that mounts the workbench
  *   GET  /api/session   Current session state (snapshot + replayed events)
- *   POST /api/events    Append review session events (same contract as MCP server)
+ *   POST /api/events    Append review session events to the stored log (same
+ *                       validation as MCP server), compare-and-swap on the
+ *                       revision the client last read
  *   GET  /api/stream    SSE stream: emits "update" events when the session file changes
  *   GET  /api/health    Health check
  *   GET  /dist/*        Compiled assets served from the dist tree (traversal-safe)

package/dist/src/console/review-console-server.js

@@ -5,18 +5,20 @@
  * Routes:
  *   GET  /              HTML shell that mounts the workbench
  *   GET  /api/session   Current session state (snapshot + replayed events)
- *   POST /api/events    Append review session events (same contract as MCP server)
+ *   POST /api/events    Append review session events to the stored log (same
+ *                       validation as MCP server), compare-and-swap on the
+ *                       revision the client last read
  *   GET  /api/stream    SSE stream: emits "update" events when the session file changes
  *   GET  /api/health    Health check
  *   GET  /dist/*        Compiled assets served from the dist tree (traversal-safe)
  */
 import { createServer } from "node:http";
 import { watch } from "node:fs";
-import { readFile as readFileAsync, writeFile as writeFileAsync, rename as renameAsync } from "node:fs/promises";
+import { readFile as readFileAsync } from "node:fs/promises";
 import { resolve, join, dirname, extname, normalize, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { defaultReviewSessionName, } from "../review-workbench/review-workbench.js";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
+import { appendReviewSessionEvents, readReviewSessionFile, reviewSessionRevision, storedReviewSessionName, updateReviewSessionFile, } from "../review-session-file.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -55,13 +57,7 @@ function distRoot() {
 // Session file helpers
 // ---------------------------------------------------------------------------
 async function readSession(path) {
-    const raw = await readFileAsync(path, "utf8");
-    return JSON.parse(raw);
-}
-async function writeSessionAtomic(path, content) {
-    const tmp = `${path}.tmp`;
-    await writeFileAsync(tmp, JSON.stringify(content, null, 2), "utf8");
-    await renameAsync(tmp, path);
+    return readReviewSessionFile(path);
 }
 // ---------------------------------------------------------------------------
 // SSE broadcaster
@@ -271,6 +267,14 @@ body {
 .connection-dot.disconnected {
   background: var(--k-negative, #ff6f6f);
 }
+.console-save-status {
+  padding: 8px 16px;
+  border-bottom: 1px solid var(--k-negative, #ff6f6f);
+  background: var(--k-panel-raised, #16202d);
+  color: var(--k-text, #eef3f8);
+  font-size: 13px;
+}
+.console-save-status[hidden] { display: none; }
 #review-workbench {
   flex: 1;
   min-height: 0;
@@ -309,31 +313,92 @@ body {
     </button>
   </div>
 </header>
+<div id="console-save-status" class="console-save-status" role="alert" data-testid="console-save-status" hidden></div>
 <main id="review-workbench" class="workbench survey-workbench-embed" data-testid="review-workbench"></main>
 <script type="module">
 import { mountReviewWorkbench, replayReviewSessionEvents, defaultReviewSessionName, buildReviewSessionEvents } from "${workbenchJsPath}";
 
 // ---- persistence adapter: POST events to /api/events ----
-function createConsoleEventStore() {
-  let _events = [];
+// One store per mount, bound to the server revision the mount was built from.
+// Each save sends only the workbench events of this mount that are not stored
+// yet; the server appends them to the stored log, so reversals and note
+// changes stay on record and decisions another writer stored (for example the
+// MCP server) are kept. Saves are serialized so each one carries the revision
+// the previous save produced. A save the server refuses (409 conflict or any
+// other failure) is never kept as local truth: the console re-fetches the
+// stored session, re-mounts from it and tells the reviewer once.
+let saveChain = Promise.resolve();
+
+function showSaveStatus(message) {
+  const el = document.getElementById("console-save-status");
+  if (!el) return;
+  if (message) {
+    el.textContent = message;
+    el.hidden = false;
+  } else {
+    el.textContent = "";
+    el.hidden = true;
+  }
+}
+
+function createConsoleEventStore(baseRevision) {
+  let revision = baseRevision;
+  // Local events of this mount already appended to the stored log.
+  let persistedCount = 0;
+  // Set once a save from this mount is refused. Saves still queued from this
+  // mount were built on the view the server just refused, and the page has
+  // re-mounted from the stored session and told the reviewer: drop them
+  // instead of reporting the same conflict again.
+  let abandoned = false;
+
+  async function refused(message) {
+    abandoned = true;
+    showSaveStatus(message);
+    await fetchAndMount();
+  }
+
+  async function persist(localEvents) {
+    if (abandoned) return;
+    const pending = localEvents.slice(persistedCount);
+    if (pending.length === 0) return;
+    let res;
+    try {
+      res = await fetch("/api/events", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ events: pending, baseRevision: revision }),
+      });
+    } catch (err) {
+      console.error("[console] Failed to persist events:", err);
+      await refused("Your last change was not saved: the console could not reach the server.");
+      return;
+    }
+    if (res.ok) {
+      const body = await res.json().catch(() => ({}));
+      if (typeof body.revision === "string") revision = body.revision;
+      persistedCount = localEvents.length;
+      showSaveStatus("");
+      return;
+    }
+    if (res.status === 409) {
+      await refused("Your last change was not saved because the session changed (another tab, reviewer or agent wrote to it). The console reloaded the current session.");
+    } else {
+      const body = await res.json().catch(() => ({}));
+      await refused("Your last change was not saved (HTTP " + res.status + (body.error ? ": " + body.error : "") + "). The console reloaded the stored session.");
+    }
+  }
+
   return {
-    load: () => _events.length > 0 ? [..._events] : undefined,
-    save: async (_session, events) => {
-      _events = [...events];
-      try {
-        await fetch("/api/events", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ events }),
-        });
-      } catch (err) {
-        console.error("[console] Failed to persist events:", err);
-      }
+    // The mount state is already replayed from the stored log.
+    load: () => undefined,
+    save: (_session, events) => {
+      const localEvents = [...events];
+      saveChain = saveChain.then(() => persist(localEvents));
+      return saveChain;
     },
   };
 }
 
-const eventStore = createConsoleEventStore();
 let activeItemName = null;
 
 async function fetchAndMount() {
@@ -341,7 +406,7 @@ async function fetchAndMount() {
     const res = await fetch("/api/session");
     if (!res.ok) throw new Error("Session fetch failed: " + res.status);
     const data = await res.json();
-    const { snapshot, events } = data;
+    const { snapshot, events, revision } = data;
     const state = events && events.length > 0
       ? replayReviewSessionEvents(snapshot, events)
       : snapshot;
@@ -354,7 +419,7 @@ async function fetchAndMount() {
     const root = document.getElementById("review-workbench");
     if (!root) return;
 
-    mountReviewWorkbench(root, state, { eventStore });
+    mountReviewWorkbench(root, state, { eventStore: createConsoleEventStore(revision) });
   } catch (err) {
     console.error("[console] Mount error:", err);
   }
@@ -451,6 +516,49 @@ async function readJsonBody(req) {
     return parsed;
 }
 // ---------------------------------------------------------------------------
+// Request guards (kontourai/survey#281)
+// ---------------------------------------------------------------------------
+function hostnameOf(hostHeader) {
+    try {
+        return new URL(`http://${hostHeader}`).hostname.replace(/^\[|\]$/g, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The server binds to loopback only, but a browser page on another site can
+ * still reach it through DNS rebinding (Host is the attacker's name) or a
+ * cross-origin "simple request" (text/plain body, foreign Origin). Each guard
+ * returns an error message, or undefined when the request passes.
+ */
+function hostGuard(req) {
+    const host = req.headers.host;
+    const hostname = host ? hostnameOf(host) : undefined;
+    return hostname && LOOPBACK_HOSTS.has(hostname) ? undefined : "Host must be a loopback address";
+}
+function originGuard(req, port) {
+    const origin = req.headers.origin;
+    if (origin === undefined)
+        return undefined;
+    try {
+        const parsed = new URL(origin);
+        const originPort = parsed.port === "" ? "80" : parsed.port;
+        const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+        if (parsed.protocol === "http:" && LOOPBACK_HOSTS.has(hostname) && originPort === String(port)) {
+            return undefined;
+        }
+    }
+    catch {
+        // Unparseable (for example "null"): refuse below.
+    }
+    return "Cross-origin writes are not allowed";
+}
+function contentTypeGuard(req) {
+    const mediaType = (req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+    return mediaType === "application/json" ? undefined : "Content-Type must be application/json";
+}
+// ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 export async function startReviewConsoleServer(options) {
@@ -464,8 +572,14 @@ export async function startReviewConsoleServer(options) {
     const stopWatcher = watchSessionFile(sessionPath, () => {
         broadcaster.broadcast("update", JSON.stringify({ ts: Date.now() }));
     });
+    let listenPort = 0;
     const server = createServer(async (req, res) => {
         try {
+            const hostError = hostGuard(req);
+            if (hostError) {
+                sendJson(res, 403, { error: hostError });
+                return;
+            }
             const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
             const pathname = url.pathname;
             // ---- Static dist assets ----
@@ -492,42 +606,80 @@ export async function startReviewConsoleServer(options) {
                     session: content.session,
                     snapshot: content.snapshot,
                     events: content.events,
+                    revision: reviewSessionRevision(content.events),
                     state: currentSessionState(content.snapshot, content.events),
                 });
                 return;
             }
             // ---- Events write (append) ----
             if (pathname === "/api/events" && req.method === "POST") {
+                const originError = originGuard(req, listenPort);
+                if (originError) {
+                    sendJson(res, 403, { error: originError });
+                    return;
+                }
+                const contentTypeError = contentTypeGuard(req);
+                if (contentTypeError) {
+                    sendJson(res, 415, { error: contentTypeError });
+                    return;
+                }
                 const body = await readJsonBody(req);
                 const incomingEvents = body.events;
+                const baseRevision = body.baseRevision;
                 if (!Array.isArray(incomingEvents)) {
                     sendJson(res, 400, { error: "events must be an array" });
                     return;
                 }
-                const content = await readSession(sessionPath);
-                const { snapshot, events: existingEvents } = content;
-                const record = createServerReviewSessionRecord({
-                    sessionName: defaultReviewSessionName,
-                    snapshot,
-                    eventCount: existingEvents.length,
-                    updatedAt: new Date(),
-                });
-                const applyResult = deriveServerReviewSessionApplyResult({
-                    record,
-                    events: incomingEvents,
-                    requiredResolvedItems: "none",
-                });
-                if (!applyResult.ok) {
-                    const issueMessages = applyResult.issues.map((issue) => "message" in issue ? issue.message : String(issue));
-                    sendJson(res, 422, { error: `Validation failed: ${issueMessages.join("; ")}` });
-                    return;
-                }
-                await writeSessionAtomic(sessionPath, {
-                    session: content.session,
-                    snapshot,
-                    events: incomingEvents,
+                const outcome = await updateReviewSessionFile(sessionPath, (content) => {
+                    const { snapshot, events: existingEvents } = content;
+                    const revision = reviewSessionRevision(existingEvents);
+                    // Compare-and-swap: the appended events express decisions made on
+                    // the reviewer's view of the log, so they are only safe to append
+                    // when that view is the log that is stored right now.
+                    if (typeof baseRevision !== "string") {
+                        return { result: { status: 428, body: { error: "baseRevision is required: send the revision from GET /api/session", revision, eventCount: existingEvents.length } } };
+                    }
+                    if (baseRevision !== revision) {
+                        return { result: { status: 409, body: { error: "Session changed since it was read; reload and retry", revision, eventCount: existingEvents.length } } };
+                    }
+                    if (incomingEvents.length === 0) {
+                        return { result: { status: 422, body: { error: "events must contain at least one event to append", revision, eventCount: existingEvents.length } } };
+                    }
+                    // Append, never replace: the stored log stays a complete record of
+                    // reviewer intent (reversals and note changes included).
+                    const nextEvents = appendReviewSessionEvents(content, incomingEvents);
+                    const record = createServerReviewSessionRecord({
+                        sessionName: storedReviewSessionName(content),
+                        snapshot,
+                        eventCount: existingEvents.length,
+                        updatedAt: new Date(),
+                    });
+                    let issueMessages;
+                    try {
+                        const applyResult = deriveServerReviewSessionApplyResult({
+                            record,
+                            events: nextEvents,
+                            requiredResolvedItems: "none",
+                        });
+                        issueMessages = applyResult.ok
+                            ? []
+                            : applyResult.issues.map((issue) => ("message" in issue ? issue.message : String(issue)));
+                    }
+                    catch (error) {
+                        issueMessages = [error instanceof Error ? error.message : String(error)];
+                    }
+                    if (issueMessages.length > 0) {
+                        return { result: { status: 422, body: { error: `Validation failed: ${issueMessages.join("; ")}` } } };
+                    }
+                    return {
+                        next: { session: content.session, snapshot, events: nextEvents },
+                        result: {
+                            status: 200,
+                            body: { ok: true, eventCount: nextEvents.length, revision: reviewSessionRevision(nextEvents) },
+                        },
+                    };
                 });
-                sendJson(res, 200, { ok: true, eventCount: incomingEvents.length });
+                sendJson(res, outcome.status, outcome.body);
                 return;
             }
             // ---- Health ----
@@ -558,6 +710,7 @@ export async function startReviewConsoleServer(options) {
     if (!address || typeof address === "string") {
         throw new Error("Unable to determine server address");
     }
+    listenPort = address.port;
     const normalizedHost = host === "::1" ? "[::1]" : host;
     const url = `http://${normalizedHost}:${address.port}/`;
     return {