@erdemtuna/doc-review 0.8.0 → 0.8.1

package/README.md

@@ -37,6 +37,20 @@ no longer need them.
 
 ## How to use /doc-review
 
+Review is opt-in: explicitly invoke `/doc-review` or ask to open an interactive
+browser review. Writing, updating, or asking for a general review of content does
+not automatically open the browser or start polling. An explicitly started review
+continues until you end it or switch tasks.
+
+After updating installed skill instructions, start a fresh agent session or reload
+skills (in Copilot CLI, `/skills reload`). Setup copies the executing package's
+skill template; rerunning setup from an older package can restore older behavior.
+Setup updates its own `AGENTS.md` guidance inside `<!-- BEGIN doc-review -->` and
+`<!-- END doc-review -->` markers. Exact, known older generated blocks are migrated.
+Custom guidance is preserved with a migration message rather than overwritten;
+update it yourself if it requests automatic review. Invalid or duplicate markers
+must be corrected before setup can proceed.
+
 ![Doc Review visual editor](assets/doc-review.png)
 
 Open an HTML or Markdown file:
@@ -87,6 +101,38 @@ npx -y @erdemtuna/doc-review poll path/to/file.html --ack b_0123456789abcdef --t
 A stale or repeated batch ID is harmless: it never clears newer feedback. The
 complete acknowledgement command is included in each response's `next_step`.
 
+### Feedback reliability and limits
+
+`poll` without `--timeout` waits for at most 12 hours. Explicit timeouts include
+server discovery, reconnection, and retry backoff, not just time spent connected.
+Recoverable connection drops are retried; invalid responses, authorization errors,
+and incompatible servers fail visibly. A timeout does not discard feedback: use
+`status` to check it, then start another poll if the review is still wanted.
+
+Each edit text or HTML field is limited to 200,000 Unicode code points. Oversized
+edits carry `truncated: true` and `truncated_fields` naming incomplete fields.
+The agent must not use partial text or HTML as a complete replacement or invent
+the rest. It must obtain the full edit from an authoritative source or ask you
+for it before acknowledging the batch.
+
+External writes to a Markdown source refresh its rendered baseline without
+clearing unsent feedback. That preserves your edits; it does not automatically
+resolve conflicts with the changed source. HTML autosaves keep their existing
+behavior.
+
+### Upgrading from v0.8.0
+
+The updated CLI requires server protocol 13. An older server that is still
+running is not silently reused or forcibly replaced. End active reviews and
+shut down that specific old server (or let it exit when idle) before restarting
+Doc Review. Keep the `.doc-review` state directory: pending batches and their
+exact receipt IDs survive a controlled restart.
+
+After installing the updated package, rerun `doc-review setup --global` for
+personal skills and `doc-review setup` in projects with generated guidance.
+Reload skills or start a fresh agent session afterward. A newer CLI paired with
+older instructions is not a complete upgrade.
+
 ## What this skill lets you do
 
 - **Edit text directly and tweak basic formatting** (e.g., bold, italic).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erdemtuna/doc-review",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Review and edit agent-generated files and localhost pages in the browser, then send the whole batch back to your agent.",
   "author": "Peter Yang",
   "homepage": "https://github.com/erdemtuna/doc-review#readme",

package/src/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: doc-review
-description: Open an HTML file, Markdown file, or localhost page in a View-first browser review so the user can optionally edit, leave contextual comments, and send all feedback back to you. Use after writing or updating something the user will read — specs, plans, reports, newsletter drafts, landing pages, slide decks, and locally running web pages.
+description: Open an HTML file, Markdown file, or localhost page for View-first interactive browser feedback. Use only when the user explicitly invokes /doc-review or requests an interactive browser review. Do not invoke merely because you write, update, discuss, or review a document or web page.
 ---
 
 # doc-review
 
+## Activation
+
+Start only when the user explicitly invokes `/doc-review` or asks to open an
+interactive browser review. A generic request to review, proofread, analyze, write,
+or update content is not permission to open this workflow. Another skill's
+automatic review step is not user permission.
+
+Without that request, respond normally without opening a review or polling for
+feedback. Once the user starts a review, continue its feedback loop until they
+end it; stop if they cancel or switch to a different task.
+
+## Review behavior
+
 The user reviews your HTML, Markdown, or localhost page in a real browser. It starts in View,
 where normal page controls work. They can switch to Edit, comment explicitly in either mode,
 and send the whole batch at once.
@@ -36,7 +49,8 @@ carried; newer comments and corrections survive.
 
 ## The loop
 
-1. Write or update the HTML or Markdown file, or start the local page being reviewed.
+1. After the explicit review request, use the requested file or localhost route.
+   Create or update content, or start a local page, only as needed for that request.
 2. Open it for the user:
 
    ```sh
@@ -56,6 +70,12 @@ carried; newer comments and corrections survive.
    npx -y @erdemtuna/doc-review poll path/to/file.html --timeout 600
    ```
 
+   Without `--timeout`, the CLI stops after 12 hours. An explicit timeout covers
+   the entire operation, including server discovery, reconnects, and backoff.
+   Recoverable connection drops retry within that deadline; terminal errors
+   require action rather than another automatic poll. The 600-second command
+   above deliberately uses a shorter deadline.
+
    Keep this command in the foreground. Do not end your turn while it is waiting.
    If your shell returns a process or session handle, keep waiting on that handle
    until the command exits. If it prints `{"status":"timeout"}`, no feedback has
@@ -119,8 +139,13 @@ One batch covers every page the user visited, grouped by file or localhost URL.
 
 ## Rules
 
+- Edits marked **`truncated`** contain incomplete fields listed in
+  `truncated_fields`. Each text/HTML field is limited to 200,000 Unicode code
+  points. Never apply a truncated field as a complete replacement or guess the
+  missing content. Obtain the complete edit from an authoritative source, or ask
+  the user for it. Do not acknowledge the batch until all feedback is handled.
 - **`edits` are changes the user already made.** `after` is their exact wording —
-  carry it across verbatim and never revert it. If the HTML was generated from
+  unless marked truncated, carry it across verbatim and never revert it. If the HTML was generated from
   something else (MDX, Markdown, a template), apply `after` to the **source** too,
   or their fix disappears on the next build.
 - When `before_html`/`after_html` are present, the user changed formatting, not

package/src/atomic-write.js

@@ -0,0 +1,53 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+const RETRY_DELAYS_MS = [10, 20, 40, 80, 160];
+const TRANSIENT_RENAME_ERRORS = new Set(["EPERM", "EACCES", "EBUSY"]);
+const waitState = new Int32Array(new SharedArrayBuffer(4));
+
+// Keep Store transactions synchronous; rename backoff blocks for at most 310ms.
+const sleepSync = (ms) => Atomics.wait(waitState, 0, 0, ms);
+
+export function createAtomicWriter({ fileSystem = fs, sleep = sleepSync, report = console.error } = {}) {
+  return function atomicWrite(file, data) {
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.doc-review.tmp`;
+    let fd;
+    let created = false;
+    try {
+      fd = fileSystem.openSync(tmp, "wx");
+      created = true;
+      fileSystem.writeFileSync(fd, data);
+      fileSystem.closeSync(fd);
+      fd = undefined;
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          fileSystem.renameSync(tmp, file);
+          return;
+        } catch (err) {
+          if (!TRANSIENT_RENAME_ERRORS.has(err.code) || attempt === RETRY_DELAYS_MS.length) throw err;
+          sleep(RETRY_DELAYS_MS[attempt]);
+        }
+      }
+    } catch (err) {
+      if (fd !== undefined) {
+        try {
+          fileSystem.closeSync(fd);
+        } catch (cleanupError) {
+          report(`Could not close atomic-write temporary file ${tmp}: ${cleanupError.message}`);
+        }
+      }
+      if (created) {
+        try {
+          fileSystem.unlinkSync(tmp);
+        } catch (cleanupError) {
+          if (cleanupError.code !== "ENOENT") {
+            report(`Could not remove atomic-write temporary file ${tmp}: ${cleanupError.message}`);
+          }
+        }
+      }
+      throw err;
+    }
+  };
+}
+
+export const atomicWrite = createAtomicWriter();

package/src/cli.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import fs from "node:fs";
-import http from "node:http";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -15,6 +14,7 @@ import {
 } from "./paths.js";
 import { readServerLock } from "./server-lock.js";
 import { installSkills, shellQuote } from "./setup.js";
+import { createDeadline, DEFAULT_POLL_SECONDS, isRecoverableTransportError, parseServerResponse, pollUntilDeadline, requestRaw } from "./poll-transport.js";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8"));
@@ -24,7 +24,7 @@ const HELP = `doc-review ${pkg.version}
   doc-review <file-or-localhost-url> Open a file or localhost page for review
   doc-review poll <target>          Wait for feedback, print it as JSON (for agents)
       --ack <batch_id>             Acknowledge that exact delivered batch, then keep waiting
-      --timeout <secs>             Exit with {"status":"timeout"} if nothing arrives
+      --timeout <secs>             End-to-end cutoff; default 12 hours (43200 seconds)
   doc-review status <target>        Report whether feedback is waiting, without blocking
   doc-review setup                  Teach Claude Code / Codex how to use doc-review
   doc-review setup --global         ...for every project, not just this one
@@ -42,72 +42,64 @@ function readServerRecord() {
   }
 }
 
-function request(server, options, body) {
-  const port = typeof server === "number" ? server : server.port;
-  const token = typeof server === "number" ? "" : server.token || "";
-  return new Promise((resolve, reject) => {
-    const req = http.request(
-      {
-        host: "127.0.0.1",
-        port,
-        ...options,
-        headers: { ...(token ? { "x-doc-review-token": token } : {}), ...(options.headers || {}) },
-      },
-      (res) => {
-        let raw = "";
-        res.setEncoding("utf8");
-        res.on("data", (chunk) => {
-          raw += chunk;
-        });
-        res.on("end", () => resolve({ status: res.statusCode, raw }));
-      }
-    );
-    req.on("error", reject);
-    if (options.timeout) req.setTimeout(options.timeout, () => req.destroy(new Error("timeout")));
-    if (body) req.write(JSON.stringify(body));
-    req.end();
-  });
-}
+const request = requestRaw;
 
-async function alive(server) {
+async function alive(server, deadline) {
+  if (!server?.port || !server.instance_id) return false;
+  const lock = readServerLock();
+  if (lock?.pid !== server.pid || lock?.instance_id !== server.instance_id) return false;
   try {
-    const lock = readServerLock();
-    if (lock?.pid !== server.pid || lock?.instance_id !== server.instance_id) return false;
-    const res = await request(server, { method: "GET", path: "/health", timeout: 1200 });
-    if (res.status !== 200) return false;
-    const health = JSON.parse(res.raw);
-    return (
-      serverProtocolMatches(health.protocol) &&
-      health.pid === server.pid &&
-      health.instance_id === server.instance_id
-    );
-  } catch {
-    return false;
+    deadline?.check();
+    const res = await request(server, {
+      method: "GET", path: "/health", timeout: Math.min(1200, deadline?.remaining() ?? 1200),
+    }, undefined, { time: deadline?.time });
+    deadline?.check();
+    const health = parseServerResponse(res);
+    if (health.pid !== server.pid || health.instance_id !== server.instance_id) {
+      throw new Error("The doc-review server identity does not match its writer lock. End the review and restart the server.");
+    }
+    if (!serverProtocolMatches(health.protocol) || !serverProtocolMatches(server.protocol)) {
+      throw new Error(
+        `Incompatible live doc-review server (protocol ${health.protocol}; this CLI requires ${SERVER_PROTOCOL}). ` +
+        "End active reviews and stop/restart the old doc-review server before retrying. " +
+        "Its live writer lock and queued feedback have not been changed.",
+      );
+    }
+    return true;
+  } catch (err) {
+    if (isRecoverableTransportError(err)) return false;
+    throw err;
   }
 }
 
-async function ensureServer() {
+async function ensureServer(deadline = createDeadline(20)) {
+  deadline.check();
   ensureStateDir();
   for (let launch = 0; launch < 3; launch += 1) {
     const saved = readServerRecord();
-    if (serverProtocolMatches(saved?.protocol) && saved.port && saved.instance_id && (await alive(saved))) return saved;
+    if (await alive(saved, deadline)) return saved;
+    deadline.check();
 
     const child = spawn(process.execPath, [path.join(here, "server-entry.js")], {
       detached: true,
       stdio: "ignore",
     });
+    let launchError;
+    child.on("error", (err) => { launchError = err; });
     child.unref();
 
     for (let attempt = 0; attempt < 60; attempt += 1) {
-      await new Promise((r) => setTimeout(r, 100));
+      await deadline.sleep(100);
+      if (launchError) throw launchError;
       const record = readServerRecord();
-      // Same protocol gate as above: a still-running server from an older
-      // version answers /health too, and must not be adopted here.
-      if (serverProtocolMatches(record?.protocol) && record.port && record.instance_id && (await alive(record))) return record;
+      if (await alive(record, deadline)) return record;
+      if (child.exitCode !== null && child.exitCode !== 0) {
+        throw new Error("The local doc-review server failed to start. Check the state directory permissions and server startup diagnostics before retrying.");
+      }
       if (child.exitCode !== null && !readServerLock()) break;
     }
   }
-  throw new Error("Could not start the local doc-review server.");
+  throw Object.assign(new Error("Could not start the local doc-review server yet."), { code: "SERVER_START_PENDING" });
 }
 
 function openBrowser(url) {
@@ -142,48 +134,6 @@ async function openCommand(input) {
   console.log(`\nWaiting for feedback? Run:\n  doc-review poll ${shellQuote(target.value)}`);
 }
 
-/**
- * One long-poll attempt. Resolves { kind: "data", raw } when the server
- * answers, or { kind: "timeout" } when the caller's deadline passes first.
- */
-function pollOnce(server, target, ackId, timeoutMs) {
-  const query = `target=${encodeURIComponent(target)}${ackId ? `&ack=${encodeURIComponent(ackId)}` : ""}`;
-  return new Promise((resolve, reject) => {
-    let done = false;
-    const settle = (fn, value) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      fn(value);
-    };
-    const req = http.request(
-      {
-        host: "127.0.0.1",
-        port: server.port,
-        method: "GET",
-        path: `/api/poll?${query}`,
-        headers: { "x-doc-review-token": server.token || "" },
-      },
-      (res) => {
-        let raw = "";
-        res.setEncoding("utf8");
-        res.on("data", (chunk) => {
-          raw += chunk;
-        });
-        res.on("end", () => settle(resolve, { kind: "data", raw: raw.trim() }));
-      }
-    );
-    const timer = timeoutMs
-      ? setTimeout(() => {
-          settle(resolve, { kind: "timeout" });
-          req.destroy();
-        }, timeoutMs)
-      : null;
-    req.on("error", (err) => settle(reject, err));
-    req.end();
-  });
-}
-
 /**
  * The consumer is an agent reading a pipe. process.exit() does not wait for
  * pending stdout writes, so a large payload could arrive truncated — always
@@ -193,50 +143,18 @@ function writeStdout(text) {
   return new Promise((resolve) => process.stdout.write(text, resolve));
 }
 
-function printTimeout(waitedSecs) {
-  const payload = {
-    status: "timeout",
-    waited_seconds: waitedSecs,
-    next_step:
-      "No feedback yet. Run the same poll command again to keep waiting, or `doc-review status <target>` to check without blocking.",
-  };
-  return writeStdout(`${JSON.stringify(payload, null, 2)}\n`);
-}
-
-async function pollCommand(input, { ackId = "", timeoutSecs = 0 } = {}) {
+async function pollCommand(input, { ackId = "", timeoutSecs = DEFAULT_POLL_SECONDS } = {}) {
+  const deadline = createDeadline(timeoutSecs);
   const target = canonicalTarget(input).value;
-  let server = await ensureServer();
 
   const label = /^https?:\/\//i.test(target) ? target : path.basename(target);
   process.stderr.write(`Waiting for feedback on ${label} — comment in the browser, then hit Send.\n`);
 
-  const deadline = timeoutSecs ? Date.now() + timeoutSecs * 1000 : null;
-  for (let attempt = 0; attempt < 3; attempt += 1) {
-    const remaining = deadline ? deadline - Date.now() : 0;
-    if (deadline && remaining <= 0) return printTimeout(timeoutSecs);
-    let result;
-    try {
-      result = await pollOnce(server, target, ackId && attempt === 0 ? ackId : "", remaining);
-    } catch (err) {
-      process.stderr.write(`Lost the connection (${err.message}); retrying.\n`);
-      server = await ensureServer();
-      continue;
-    }
-    if (result.kind === "timeout") return printTimeout(timeoutSecs);
-    if (!result.raw) {
-      server = await ensureServer();
-      continue;
-    }
-    try {
-      const batch = JSON.parse(result.raw);
-      await writeStdout(`${JSON.stringify(batch, null, 2)}\n`);
-      return;
-    } catch {
-      process.stderr.write("Unexpected response from the doc-review server; retrying.\n");
-    }
-  }
-  process.stderr.write("Gave up waiting for feedback.\n");
-  process.exit(1);
+  const batch = await pollUntilDeadline({
+    target, ackId, deadline, discover: ensureServer,
+    diagnostic: (text) => process.stderr.write(text),
+  });
+  await writeStdout(`${JSON.stringify(batch, null, 2)}\n`);
 }
 
 /**
@@ -297,7 +215,7 @@ process.on("SIGINT", () => {
 });
 
 function parsePollArgs(rest) {
-  const parsed = { file: "", ackId: "", timeoutSecs: 0 };
+  const parsed = { file: "", ackId: "", timeoutSecs: DEFAULT_POLL_SECONDS };
   let sawTimeout = false;
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];

package/src/edit-limits.js

@@ -0,0 +1,23 @@
+export const MAX_EDIT_CHARACTERS = 200_000;
+
+const EDIT_FIELDS = ["before", "after", "before_html", "after_html", "moved_after", "moved_before"];
+
+export function limitEditFields(input) {
+  const fields = {};
+  const truncatedFields = [];
+  for (const field of EDIT_FIELDS) {
+    const value = input[field];
+    if (typeof value !== "string") continue;
+    let end = 0;
+    let count = 0;
+    // Count Unicode code points, not UTF-16 halves of an astral character.
+    for (const character of value) {
+      if (count === MAX_EDIT_CHARACTERS) break;
+      end += character.length;
+      count += 1;
+    }
+    fields[field] = value.slice(0, end);
+    if (end < value.length) truncatedFields.push(field);
+  }
+  return { fields, truncated: truncatedFields.length > 0, truncated_fields: truncatedFields };
+}

package/src/paths.js

@@ -5,7 +5,7 @@ import fs from "node:fs";
 
 // Bump this when the CLI and detached server no longer share the same request
 // contract. A new CLI must not silently reuse an older background server.
-export const SERVER_PROTOCOL = 12;
+export const SERVER_PROTOCOL = 13;
 
 export function serverProtocolMatches(protocol) {
   return Number(protocol) === SERVER_PROTOCOL;

package/src/poll-transport.js

@@ -0,0 +1,222 @@
+import http from "node:http";
+import { performance } from "node:perf_hooks";
+
+export const DEFAULT_POLL_SECONDS = 12 * 60 * 60;
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const clock = {
+  now: () => performance.now(),
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (timer) => clearTimeout(timer),
+};
+
+function codedError(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+
+export function createDeadline(seconds = DEFAULT_POLL_SECONDS, time = clock) {
+  const end = time.now() + seconds * 1000;
+  const remaining = () => Math.max(0, end - time.now());
+  const check = () => {
+    if (remaining() <= 0) throw codedError("Polling deadline reached.", "POLL_DEADLINE");
+  };
+  return {
+    seconds,
+    time,
+    remaining,
+    check,
+    async sleep(ms) {
+      check();
+      await new Promise((resolve) => time.setTimeout(resolve, Math.min(ms, remaining(), MAX_TIMER_MS)));
+      check();
+    },
+  };
+}
+
+export function isRecoverableTransportError(err) {
+  return new Set([
+    "ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EHOSTUNREACH",
+    "ENETUNREACH", "ENETDOWN", "ECONNABORTED", "ERR_STREAM_PREMATURE_CLOSE",
+    "SERVER_START_PENDING",
+  ]).has(err?.code);
+}
+
+/**
+ * An absolute response deadline, not a socket-idle timeout: heartbeats and
+ * partially received JSON must not extend the caller's waiting budget.
+ */
+export function requestRaw(server, options, body, {
+  timeoutMs = options.timeout,
+  time = clock,
+  signal,
+  timeoutCode = "ETIMEDOUT",
+  makeRequest = http.request,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    let req;
+    let res;
+    let timer;
+    let done = false;
+    let ended = false;
+    let raw = "";
+    const expires = timeoutMs == null ? null : time.now() + timeoutMs;
+    const premature = () => codedError("The server closed an incomplete response.", "ERR_STREAM_PREMATURE_CLOSE");
+    const cleanupResponse = () => {
+      res?.removeListener("data", onData);
+      res?.removeListener("end", onEnd);
+      res?.removeListener("aborted", onAborted);
+    };
+    const settle = (err, value) => {
+      if (done) return;
+      done = true;
+      time.clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      cleanupResponse();
+      // Keep error handlers until close: destroying a socket may emit one last
+      // error asynchronously. Close removes the remaining owned listeners.
+      res?.destroy();
+      req?.destroy();
+      if (err) reject(err);
+      else resolve(value);
+    };
+    const onError = (err) => settle(err);
+    const onData = (chunk) => { raw += chunk; };
+    const onEnd = () => {
+      ended = true;
+      if (!res.complete) return settle(premature());
+      settle(null, { status: res.statusCode, raw });
+    };
+    const onAborted = () => settle(premature());
+    const onResponseClose = () => {
+      if (!ended) settle(premature());
+      cleanupResponse();
+      res.removeListener("error", onError);
+      res.removeListener("close", onResponseClose);
+    };
+    const onRequestClose = () => {
+      if (!done) settle(premature());
+      req.removeListener("error", onError);
+      req.removeListener("close", onRequestClose);
+      req.removeListener("response", onResponse);
+    };
+    const onAbort = () => settle(codedError("Polling cancelled.", "ABORT_ERR"));
+    const armTimer = () => {
+      const left = expires - time.now();
+      if (left <= 0) return settle(codedError("Polling request timed out.", timeoutCode));
+      timer = time.setTimeout(armTimer, Math.min(left, MAX_TIMER_MS));
+    };
+    const onResponse = (response) => {
+      res = response;
+      if (done) {
+        res.destroy();
+        return;
+      }
+      res.setEncoding("utf8");
+      res.on("data", onData);
+      res.on("end", onEnd);
+      res.on("error", onError);
+      res.on("aborted", onAborted);
+      res.on("close", onResponseClose);
+    };
+    try {
+      if (signal?.aborted) return onAbort();
+      const port = typeof server === "number" ? server : server.port;
+      const token = typeof server === "number" ? "" : server.token || "";
+      const { timeout: _timeout, ...requestOptions } = options;
+      req = makeRequest({
+        host: "127.0.0.1",
+        port,
+        ...requestOptions,
+        headers: { ...(token ? { "x-doc-review-token": token } : {}), ...(options.headers || {}) },
+      });
+      req.on("response", onResponse);
+      req.on("error", onError);
+      req.on("close", onRequestClose);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (expires !== null) armTimer();
+      if (done) return;
+      if (body) req.write(JSON.stringify(body));
+      req.end();
+    } catch (err) {
+      settle(err);
+    }
+  });
+}
+
+export function parseServerResponse(response) {
+  if (response.status !== 200) {
+    let detail = "";
+    try { detail = JSON.parse(response.raw).error || ""; } catch { /* HTTP status is sufficient. */ }
+    throw codedError(
+      `Doc-review server returned HTTP ${response.status}${detail ? `: ${detail}` : "."}`,
+      "SERVER_RESPONSE_ERROR",
+    );
+  }
+  try {
+    const parsed = JSON.parse(response.raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+    return parsed;
+  } catch {
+    throw codedError("Malformed response from the doc-review server. End the review and restart the server.", "SERVER_RESPONSE_INVALID");
+  }
+}
+
+export async function pollOnce(server, target, ackId, deadline) {
+  deadline.check();
+  const query = `target=${encodeURIComponent(target)}${ackId ? `&ack=${encodeURIComponent(ackId)}` : ""}`;
+  const response = await requestRaw(server, {
+    method: "GET",
+    path: `/api/poll?${query}`,
+  }, undefined, {
+    timeoutMs: deadline.remaining(),
+    time: deadline.time,
+    timeoutCode: "POLL_DEADLINE",
+  });
+  // Graceful server disposal ends the space heartbeats without a JSON payload.
+  // HTTP is complete, but this poll was interrupted just like a dropped socket.
+  if (response.status === 200 && /^ +$/.test(response.raw)) {
+    throw codedError("The server ended the poll before sending feedback.", "ERR_STREAM_PREMATURE_CLOSE");
+  }
+  const batch = parseServerResponse(response);
+  if (!["feedback", "closed", "timeout"].includes(batch.status) ||
+      (batch.status === "feedback" && (typeof batch.batch_id !== "string" || !batch.batch_id || !Array.isArray(batch.pages)))) {
+    throw codedError("Malformed polling response from the doc-review server.", "SERVER_RESPONSE_INVALID");
+  }
+  return batch;
+}
+
+export async function pollUntilDeadline({
+  target,
+  ackId = "",
+  deadline = createDeadline(),
+  discover,
+  poll = pollOnce,
+  diagnostic = () => {},
+}) {
+  let failures = 0;
+  for (;;) {
+    try {
+      deadline.check();
+      const server = await discover(deadline);
+      deadline.check();
+      // An uncertain send must repeat the supplied receipt, never a newer ID.
+      const batch = await poll(server, target, ackId, deadline);
+      deadline.check();
+      return batch;
+    } catch (err) {
+      if (err.code === "POLL_DEADLINE" || deadline.remaining() <= 0) {
+        return {
+          status: "timeout",
+          waited_seconds: deadline.seconds,
+          next_step: "No feedback yet. Run the same poll command again to keep waiting, or `doc-review status <target>` to check without blocking.",
+        };
+      }
+      if (!isRecoverableTransportError(err)) throw err;
+      diagnostic(`Lost the connection (${err.message}); retrying.\n`);
+      try {
+        await deadline.sleep(Math.min(250 * 2 ** Math.min(failures++, 5), 5000));
+      } catch (sleepError) {
+        if (sleepError.code !== "POLL_DEADLINE") throw sleepError;
+      }
+    }
+  }
+}

package/src/server.js

@@ -10,6 +10,7 @@ import { isMarkdown, renderMarkdownPage } from "./markdown.js";
 import { canonicalTarget, ensureStateDir, localUrl, SERVER_PROTOCOL, serverPath, stateDir, targetKey } from "./paths.js";
 import { acquireServerLock, releaseServerLock, removeOwnedServerRecord } from "./server-lock.js";
 import { invocation, shellQuote } from "./setup.js";
+import { limitEditFields } from "./edit-limits.js";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
@@ -224,8 +225,13 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
       const current = hash(html);
       // Our own autosave must never bounce back as a reload.
       if (lastWritten.get(key) === current) return;
+      try {
+        store.setPristine(key, html, { keepEdits: isMarkdown(page.file) });
+      } catch (err) {
+        console.error(`Could not refresh review baseline for ${page.file}: ${err.message}`);
+        return;
+      }
       lastWritten.set(key, current);
-      store.setPristine(key, html);
       for (const session of sessionsForKey(key)) {
         invalidateSessionRender(session);
         emit(session, "reload", { key });
@@ -284,6 +290,7 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
           kind: e.kind,
           before: e.before,
           after: e.after,
+          ...(e.truncated ? { truncated: true, truncated_fields: e.truncated_fields } : {}),
           ...(e.before_html !== undefined && e.before_html !== e.before ? { before_html: e.before_html } : {}),
           ...(e.after_html !== undefined && e.after_html !== e.after ? { after_html: e.after_html } : {}),
           ...(Array.isArray(e.staged_assets) && e.staged_assets.length ? { staged_assets: e.staged_assets } : {}),
@@ -314,6 +321,7 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
     const hasMarkdown = pages.some((p) => p.kind === "file" && isMarkdown(p.file));
     const hasUrl = pages.some((p) => p.kind === "url");
     const hasCorrections = pages.some((p) => p.comments.some((c) => c.correction));
+    const hasTruncation = pages.some((p) => p.edits.some((e) => e.truncated));
     const id = `b_${crypto.randomBytes(12).toString("hex")}`;
     const entry = store.page(session.entryKey);
     const pollTarget = entry?.kind === "url" ? entry.url : entry?.file;
@@ -326,9 +334,14 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
       sent_at: new Date().toISOString(),
       next_step:
         "Apply this feedback. Each entry in `pages` names the reviewed file or localhost URL. Items under `edits` are " +
-        "changes the human already made: `after` is their exact new wording, so carry it across verbatim, and " +
+        "changes the human already made: unless marked `truncated`, `after` is their exact new wording, so carry it across verbatim, and " +
         "never revert it. When an edit carries `after_html`, the human changed formatting (bold, italic, links) — " +
         "use the HTML version, translated into the source's own syntax. " +
+        (hasTruncation
+          ? "Some edits are marked `truncated`; `truncated_fields` lists incomplete fields. Never apply incomplete text or HTML " +
+            "as a complete replacement or invent missing content. Recover the full edit only from an authoritative source, " +
+            "or ask the user for it. Do not acknowledge this batch until all feedback is handled. "
+          : "") +
         (hasMarkdown
           ? "Markdown pages were reviewed rendered, so quotes and `after` wording use the rendered text — apply " +
             "the change to the Markdown source, keeping its formatting syntax. "
@@ -873,7 +886,11 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
           const body = await readBody(req);
           const label = String(body.label || "Document");
           const kind = body.kind === "deleted" ? "deleted" : body.kind === "moved" ? "moved" : "edited";
-          const cap = (s) => (typeof s === "string" ? s.slice(0, 4000) : undefined);
+          const limited = limitEditFields({
+            before: body.before, after: body.after, before_html: body.before_html, after_html: body.after_html,
+            ...(kind === "moved" ? { moved_after: body.moved_after, moved_before: body.moved_before } : {}),
+          });
+          const fields = limited.fields;
           const stagedRoot = path.join(stateDir(), "pasted", key);
           const stagedAssets = Array.isArray(body.staged_assets)
             ? body.staged_assets
@@ -893,10 +910,12 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
                 .map(({ path: assetPath, preview_src }) => ({ path: assetPath, preview_src }))
             : [];
           const extra = {
-            ...(kind === "moved" ? { moved_after: cap(body.moved_after) || "", moved_before: cap(body.moved_before) || "" } : {}),
+            truncated: limited.truncated,
+            truncated_fields: limited.truncated_fields,
+            ...(kind === "moved" ? { moved_after: fields.moved_after || "", moved_before: fields.moved_before || "" } : {}),
             ...(stagedAssets.length ? { staged_assets: stagedAssets } : {}),
           };
-          store.addEdit(key, label, kind, cap(body.before), cap(body.after), cap(body.before_html), cap(body.after_html), extra);
+          store.addEdit(key, label, kind, fields.before, fields.after, fields.before_html, fields.after_html, extra);
           return json(res, 200, { page: pageState(key) });
         }
 

package/src/setup-guidance.js

@@ -0,0 +1,128 @@
+export const GUIDANCE_BEGIN = "<!-- BEGIN doc-review -->";
+export const GUIDANCE_END = "<!-- END doc-review -->";
+
+// Historical generated text is deliberately independent of the current guidance.
+const LEGACY_TAIL = `
+\`npx -y @erdemtuna/doc-review <file.html>\`. For a locally running web page, open the real
+route with \`npx -y @erdemtuna/doc-review http://localhost:3000/path\` instead of recreating
+it as a static file. Then block on
+\`npx -y @erdemtuna/doc-review poll <target> --timeout 600\` until they send feedback.
+If it prints \`{"status":"timeout"}\`, no feedback arrived yet — run the same
+poll command again to keep waiting. When a \`{"status":"feedback"}\` batch
+arrives, apply it, then run the exact acknowledgement command in its
+\`next_step\`, which uses \`--ack <batch_id>\`.
+
+Keep the poll command in the foreground and do not end the turn while it waits.
+If the shell returns a process or session handle, keep waiting on that handle until
+the command exits. \`npx -y @erdemtuna/doc-review status <target>\` reports instantly
+whether feedback is already waiting, without blocking.
+
+The batch groups feedback by page under \`pages\`, so fix every page listed. Items
+under \`edits\` are changes the user already made: \`after\` is their exact wording,
+so carry it across verbatim and never revert it — and if the HTML was generated
+from MDX or Markdown, apply it to the source too. Markdown files open rendered
+and are never written by doc-review: apply their comments and edits to the
+Markdown source, keeping its syntax. There is no reply channel; the user sees
+your work when the page reloads. For a localhost page, direct edits and deletions
+arrive with \`kind: "url"\`; find and update the matching MDX, TSX, template, or
+component source. Never write the rendered HTTP response over project source.`;
+
+export const LEGACY_GUIDANCE = Object.freeze([
+  `## Reviewing files and localhost pages with doc-review
+
+After writing an HTML or Markdown file the user will read, open it for them with${LEGACY_TAIL}`,
+  `## Reviewing files and localhost pages with doc-review
+
+Start only when the user explicitly invokes /doc-review or requests an
+interactive browser review. Writing, updating, discussing, or generically reviewing
+content does not authorize opening a review or polling. Another skill's automatic
+review step is not user permission. Otherwise respond normally.
+
+After that explicit request, open the requested HTML or Markdown file with${LEGACY_TAIL}`,
+]);
+
+const migrationMessage = "AGENTS.md contains custom or unrecognized doc-review guidance — left it unchanged. " +
+  "Manually reconcile that guidance, then wrap only the setup-owned section in " +
+  `${GUIDANCE_BEGIN} and ${GUIDANCE_END}, or remove it and re-run setup.`;
+
+function invalidMarkers() {
+  throw new Error("AGENTS.md has malformed, duplicate, or ambiguous doc-review ownership markers. " +
+    "Keep exactly one standalone BEGIN/END pair in order, then re-run setup. No setup files were changed.");
+}
+
+function render(body, newline) {
+  return `${GUIDANCE_BEGIN}\n${body.trim()}\n${GUIDANCE_END}`.replaceAll("\n", newline);
+}
+
+/** Plan the complete edit before setup writes any files. Never normalize user text. */
+export function updateGuidance(existing, body) {
+  const lines = [...existing.matchAll(/[^\n]*(?:\n|$)/g)]
+    .filter((match) => match[0])
+    .map((match) => ({
+      text: match[0].replace(/\r?\n$/, ""),
+      start: match.index,
+      end: match.index + match[0].replace(/\r?\n$/, "").length,
+    }));
+  const markers = lines.filter(({ text }) => /doc-review/i.test(text) &&
+    (/\b(?:BEGIN|END)\b/i.test(text) && /<!--|-->|^\s*(?:BEGIN|END)\b/i.test(text)));
+
+  if (markers.length) {
+    if (markers.length !== 2 || markers[0].text !== GUIDANCE_BEGIN || markers[1].text !== GUIDANCE_END) {
+      invalidMarkers();
+    }
+    const [begin, end] = markers;
+    const newline = existing.slice(begin.end).startsWith("\r\n") ? "\r\n" : "\n";
+    return {
+      contents: existing.slice(0, begin.start) + render(body, newline) + existing.slice(end.end),
+      message: "Updated setup-owned AGENTS.md guidance   (Codex)",
+    };
+  }
+
+  const candidates = [];
+  for (const legacy of LEGACY_GUIDANCE) {
+    for (const command of ["npx -y @erdemtuna/doc-review", "doc-review"]) {
+      for (const newline of ["\n", "\r\n"]) {
+        const text = legacy.replaceAll("npx -y @erdemtuna/doc-review", command).replaceAll("\n", newline);
+        let start = existing.indexOf(text);
+        while (start !== -1) {
+          const end = start + text.length;
+          const before = existing.slice(0, start);
+          const after = existing.slice(end);
+          // A complete generated section, not a substring of customized prose.
+          if ((start === 0 || before.endsWith("\n") || before === "\uFEFF") &&
+              /^(?:\r?\n|$)/.test(after) &&
+              /^(?:\s*$|(?:\r?\n)+(?=#{1,2} ))/.test(after)) {
+            candidates.push({ start, end, newline });
+          }
+          start = existing.indexOf(text, start + text.length);
+        }
+      }
+    }
+  }
+  if (candidates.length > 1) {
+    throw new Error("AGENTS.md contains multiple legacy doc-review sections; ownership is ambiguous. " +
+      "Reconcile them before re-running setup. No setup files were changed.");
+  }
+  if (candidates.length === 1) {
+    const { start, end, newline } = candidates[0];
+    const surrounding = existing.slice(0, start) + existing.slice(end);
+    if (!/doc-review/i.test(surrounding)) {
+      return {
+        contents: existing.slice(0, start) + render(body, newline) + existing.slice(end),
+        message: "Migrated legacy AGENTS.md guidance to setup-owned markers   (Codex)",
+      };
+    }
+  }
+  if (/doc-review/i.test(existing)) {
+    return { contents: existing, message: migrationMessage };
+  }
+
+  const newline = existing.includes("\r\n") ? "\r\n" : "\n";
+  const separator = !existing || existing.endsWith(newline + newline)
+    ? ""
+    : existing.endsWith("\n") ? newline : newline + newline;
+  return {
+    contents: existing + separator + render(body, newline) + newline,
+    message: `${existing ? "Updated" : "Created"} AGENTS.md   (Codex)`,
+  };
+}

package/src/setup.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { updateGuidance } from "./setup-guidance.js";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_NAME = "@erdemtuna/doc-review";
@@ -50,15 +51,26 @@ export const skillFor = (cmd) => readSkill().replaceAll(NPX_COMMAND, cmd);
 const CODEX_BLOCK = `
 ## Reviewing files and localhost pages with doc-review
 
-After writing an HTML or Markdown file the user will read, open it for them with
+Start only when the user explicitly invokes /doc-review or requests an
+interactive browser review. Writing, updating, discussing, or generically reviewing
+content does not authorize opening a review or polling. Another skill's automatic
+review step is not user permission. Otherwise respond normally.
+
+After that explicit request, open the requested HTML or Markdown file with
 \`${NPX_COMMAND} <file.html>\`. For a locally running web page, open the real
 route with \`${NPX_COMMAND} http://localhost:3000/path\` instead of recreating
 it as a static file. Then block on
 \`${NPX_COMMAND} poll <target> --timeout 600\` until they send feedback.
 If it prints \`{"status":"timeout"}\`, no feedback arrived yet — run the same
 poll command again to keep waiting. When a \`{"status":"feedback"}\` batch
-arrives, apply it, then run the exact acknowledgement command in its
-\`next_step\`, which uses \`--ack <batch_id>\`.
+arrives, handle every item, then run the exact acknowledgement command in its
+\`next_step\`, which uses \`--ack <batch_id>\`. Keep that exact batch ID on retries;
+never acknowledge an unhandled batch.
+
+Without \`--timeout\`, the CLI defaults to a 12-hour cutoff. An explicit
+\`--timeout\` is one end-to-end deadline, including server discovery and reconnect
+attempts. Keep using the bounded foreground \`--timeout 600\` loop above;
+those polls do not wait 12 hours.
 
 Keep the poll command in the foreground and do not end the turn while it waits.
 If the shell returns a process or session handle, keep waiting on that handle until
@@ -66,9 +78,19 @@ the command exits. \`${NPX_COMMAND} status <target>\` reports instantly
 whether feedback is already waiting, without blocking.
 
 The batch groups feedback by page under \`pages\`, so fix every page listed. Items
-under \`edits\` are changes the user already made: \`after\` is their exact wording,
-so carry it across verbatim and never revert it — and if the HTML was generated
-from MDX or Markdown, apply it to the source too. Markdown files open rendered
+under \`edits\` are changes the user already made. For non-truncated edits,
+\`after\` is their exact wording: carry it across verbatim and never revert it.
+If the HTML was generated from MDX or Markdown, apply complete edits to the
+source too.
+
+Edit fields are limited to 200,000 Unicode code points each. An edit with
+\`truncated: true\` identifies clipped fields in the \`truncated_fields\` array.
+Never apply incomplete text or HTML as a complete replacement or invent missing
+text. Recover the full edit only from an authoritative source; otherwise ask the
+user for the complete edit. Do not acknowledge the batch until every item,
+including truncated edits, has been handled.
+
+Markdown files open rendered
 and are never written by doc-review: apply their comments and edits to the
 Markdown source, keeping its syntax. There is no reply channel; the user sees
 your work when the page reloads. For a localhost page, direct edits and deletions
@@ -79,6 +101,17 @@ component source. Never write the rendered HTTP response over project source.
 export function installSkills(cwd, { global: isGlobal = false, home = os.homedir(), command } = {}) {
   const done = [];
   const cmd = command || invocation();
+  const agents = path.join(cwd, "AGENTS.md");
+  let guidance;
+  let existing;
+  if (!isGlobal) {
+    const bytes = fs.existsSync(agents) ? fs.readFileSync(agents) : Buffer.alloc(0);
+    existing = bytes.toString("utf8");
+    if (!Buffer.from(existing, "utf8").equals(bytes)) {
+      throw new Error("AGENTS.md is not valid UTF-8; convert it before re-running setup. No setup files were changed.");
+    }
+    guidance = updateGuidance(existing, CODEX_BLOCK.replaceAll(NPX_COMMAND, cmd));
+  }
 
   const skillRoots = isGlobal
     ? [
@@ -96,15 +129,8 @@ export function installSkills(cwd, { global: isGlobal = false, home = os.homedir
   }
 
   if (!isGlobal) {
-    const agents = path.join(cwd, "AGENTS.md");
-    const existing = fs.existsSync(agents) ? fs.readFileSync(agents, "utf8") : "";
-    if (existing.includes("doc-review")) {
-      done.push("AGENTS.md already mentions doc-review — left it alone");
-    } else {
-      const block = CODEX_BLOCK.replaceAll(NPX_COMMAND, cmd);
-      fs.writeFileSync(agents, existing ? `${existing.trimEnd()}\n${block}` : block.trimStart());
-      done.push(`${existing ? "Updated" : "Created"} AGENTS.md   (Codex)`);
-    }
+    if (guidance.contents !== existing) fs.writeFileSync(agents, guidance.contents);
+    done.push(guidance.message);
   }
 
   done.push("", `Agents will be told to run: ${cmd}`);

package/src/state.js

@@ -3,6 +3,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { normalizeCommentAnchor } from "./comment-anchor.js";
 import { canonicalTarget, ensureStateDir, pageKey, realFile, statePath, targetKey } from "./paths.js";
+export { atomicWrite } from "./atomic-write.js";
+import { atomicWrite } from "./atomic-write.js";
 
 /** Anything untouched this long is review debris, not work in progress. */
 const PRUNE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
@@ -92,24 +94,6 @@ function normalizeState(parsed, makeBatchId) {
   return { data, changed };
 }
 
-/**
- * Atomic write via a unique sibling tmp file. The name is unguessable and the
- * create is exclusive, so a pre-planted symlink can never redirect the write,
- * and a failed rename never leaves a predictable orphan behind.
- */
-export function atomicWrite(file, data) {
-  const tmp = `${file}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.doc-review.tmp`;
-  fs.writeFileSync(tmp, data, { flag: "wx" });
-  try {
-    fs.renameSync(tmp, file);
-  } catch (err) {
-    try {
-      fs.unlinkSync(tmp);
-    } catch {}
-    throw err;
-  }
-}
-
 /**
  * All durable state lives in one JSON file. No database, no network.
  *
@@ -343,6 +327,19 @@ export class Store {
         if (afterHtml !== undefined) row.after_html = afterHtml;
         // A re-move of the same block replaces its landing spot.
         if (extra) {
+          if (Array.isArray(extra.truncated_fields)) {
+            const replaced = new Set([
+              ...(after !== undefined ? ["after"] : []),
+              ...(afterHtml !== undefined ? ["after_html"] : []),
+              ...["moved_after", "moved_before"].filter((field) => extra[field] !== undefined),
+            ]);
+            // Original before text is retained across edits, including its truncation.
+            const truncatedFields = [...new Set([
+              ...(row.truncated_fields || []).filter((field) => !replaced.has(field)),
+              ...extra.truncated_fields.filter((field) => replaced.has(field)),
+            ])];
+            extra = { ...extra, truncated: truncatedFields.length > 0, truncated_fields: truncatedFields };
+          }
           if (extra.staged_assets) {
             const assets = [...(row.staged_assets || []), ...extra.staged_assets];
             extra = { ...extra, staged_assets: [...new Map(assets.map((asset) => [asset.path, asset])).values()] };
@@ -363,10 +360,10 @@ export class Store {
   }
 
   /** After the agent writes, its version becomes the new revert target. */
-  setPristine(key, html) {
+  setPristine(key, html, { keepEdits = false } = {}) {
     return this.update(key, (page) => {
       page.pristine = html;
-      page.edits = [];
+      if (!keepEdits) page.edits = [];
     });
   }