create-pmos 0.7.1 → 0.7.3

package/README.md

@@ -333,6 +333,74 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.7.3
+
+**A fix — read this if you ran a document review on 0.7.1 or 0.7.2, and especially if you have more
+than one repository open in the workspace.**
+
+Reviews were filed into the **workspace app's own install directory** rather than into the repository
+being reviewed. Two consequences, and the first is the one that matters:
+
+- **Reviews from different repositories were pooled together.** Open two repos and the review you
+  filed against one appeared when you opened the review surface in the other. A review names the
+  documents it read and quotes their contents, so this put one project's material in front of
+  another — including in front of an agent session working in that second repo.
+- **In a product repo using this kit, reviews were written nowhere useful.** The review skill was
+  written against PMOS's own layout and told the agent to write to `workspace/state/reviews/` and
+  read `workspace/state/needs.json`. **A product repo has no `workspace/` folder**, so the agent
+  either created a stray one or filed the review where nothing would ever read it.
+
+**Both are fixed.** Reviews now resolve through the same per-workspace state directory that
+`needs.json` and `acceptances.jsonl` already used — your repo's own `pmos/state/reviews/`. The skill
+no longer assumes any layout: the paths it needs are passed to it as absolute facts.
+
+**If you reviewed anything on 0.7.1 or 0.7.2**, look in the workspace app's install directory under
+`workspace/state/reviews/` for reviews that belong to your repositories, and delete any you would
+rather not have sitting there. Nothing was sent anywhere — this is local files in the wrong folder —
+but if you had two repos open, they saw each other.
+
+**And the reason you probably never ran one: there was no way to say what to review.** The skill could
+only be launched from the scheduled lens, and a schedule carries no scope — so its own instruction to
+read exactly the documents you named had nothing behind it.
+
+- **A `review` control now sits on the open document.** You are reading a document; you click
+  `review`; an agent reviews *that* document. Nothing to type, no schedule to create. The scope is
+  the thing in front of you.
+
+**The standing disclosure is unchanged**, and it still matters more than any of the above: the review
+surface has **not** been through its own review gate, and its false-positive rate is unmeasured. The
+guard that withholds any proposal which would close a recorded open question or overwrite a decision
+is tested, including in a real browser. How often its findings are simply *wrong* is not yet known.
+
+## What's new in 0.7.2
+
+**A fix — read this if you use the Terminal Workspace on a machine with `tmux` installed.**
+
+0.7.0 and 0.7.1 both shipped a workspace terminal that renders **gibberish** there. Box-drawing
+characters, check marks, spinners, emoji and accented letters all arrived damaged, and the output
+lost its structure — which matters because agent CLIs print those constantly, so in practice most
+frames were affected. If your terminal has looked broken since 0.7.0, this is why, and it was our
+bug, not your setup.
+
+The cause: the workspace drives `tmux` in control mode, and that stream is **bytes**. `tmux` escapes
+only the control characters and the backslash — every byte of a UTF-8 character passes through raw.
+The workspace decoded that stream as text and then narrowed it back to bytes, which does not merely
+lose characters, it *manufactures* control codes out of the wreckage. `┌` became a **form feed**,
+which is why the layout collapsed and not just the glyphs.
+
+- **Fixed.** The control stream is now handled as bytes end to end, with a single UTF-8 decode in
+  one place. A character split across two `tmux` frames still survives.
+- **A second, smaller source of the same symptom, also fixed.** The scrollback ring trims from the
+  front once it fills, and it used to cut at an arbitrary offset — routinely *inside* an escape
+  sequence, so the leftover fragment replayed as literal rubble like `5;203m` when you reattached.
+  It now cuts at a line boundary.
+- **Nothing else changed.** 0.7.2 carries this fix and only this fix.
+
+**You were only affected if `tmux` is on your PATH.** The workspace falls back to a direct terminal
+when it is not, and that path never had the defect — which is exactly why this survived two
+releases. The regression test now reports which of the two transports it exercised, so a green run
+on a machine without `tmux` can no longer read as if it had covered the one that broke.
+
 ## What's new in 0.7.1
 
 **A correction to 0.7.0 — read this if you used the review surface.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@0c57593
+kernel-source: pmos@56ab797
 assembled: 2026-07-28
 mode: vendor

package/workspace/lib/tmux-control.js

@@ -17,28 +17,55 @@
 // The protocol, as it actually arrives on the wire:
 //   \x1bP1000p                       DCS introducer, once, before the first line
 //   %begin <t> <n> <f> … %end        a command's reply is wrapped in a begin/end block
-//   %output %0 line-1\015\012…       pane bytes, NON-PRINTABLES OCTAL-ESCAPED (\015 = CR)
+//   %output %0 line-1\015\012…       pane bytes, with SOME bytes octal-escaped (\015 = CR)
 //   %exit [reason]                   the control client is going away
 //   %session-changed, %window-*, …   notifications we do not need
-// Lines are CRLF-terminated. Because every byte outside printable ASCII is octal-escaped, the
-// control stream itself is pure ASCII — so reading the client PTY as utf8 is safe, and the real
-// UTF-8 decoding happens HERE, after unescaping, with a streaming decoder (a multi-byte character
-// can be split across two %output frames).
+//
+// THE CONTROL STREAM IS BYTES, NOT TEXT. tmux escapes only `c < 0x20` and the backslash itself
+// (control.c); every byte >= 0x80 is written through RAW. So a `─` (E2 94 80) arrives on the wire
+// as three raw high bytes, NOT as three octal escapes. Reading the client PTY as a utf8 STRING and
+// then narrowing each code unit back to a byte therefore destroys every non-ASCII character —
+// U+2500 & 0xff = 0x00, U+250C & 0xff = 0x0C (a form feed), U+2713 & 0xff = 0x13 — which is
+// injected control codes and replacement characters in the pane: box-drawing rubble, mangled
+// layout, gibberish. Verified against tmux 3.4.
+//
+// So this parser works on BUFFERS end to end, and the single UTF-8 decode happens HERE, after
+// unescaping, with a per-pane streaming decoder (a multi-byte character can be split across two
+// %output frames). The caller must read the control client's PTY with `encoding: null`.
 
 const { StringDecoder } = require('string_decoder');
 
+const LF = 0x0a, CR = 0x0d, BACKSLASH = 0x5c, SPACE = 0x20, PCT = 0x25;
+const EMPTY = Buffer.alloc(0);
+const DCS = Buffer.from('\x1bP1000p', 'latin1');       // introducer, once, before the first line
+const ST = Buffer.from('\x1b\\', 'latin1');            // string terminator, may trail the last
+
+const isOct = (b) => b >= 0x30 && b <= 0x37;
+
+// A control-mode chunk is a byte stream. A string is accepted for ASCII test fixtures and is read
+// as latin1 — one code unit per byte — because that is the only faithful string view of bytes.
+const toBytes = (chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'latin1'));
+
+function startsWithAscii(buf, s) {
+  if (buf.length < s.length) return false;
+  for (let i = 0; i < s.length; i++) if (buf[i] !== s.charCodeAt(i)) return false;
+  return true;
+}
+
 // tmux escapes a byte as a backslash + exactly three octal digits (backslash itself is \134),
-// so there is no two-character `\\` case to handle — only the octal form.
-function unescapeToBytes(s) {
-  const out = Buffer.allocUnsafe(s.length);
+// so there is no two-character `\\` case to handle — only the octal form. Every other byte,
+// INCLUDING the raw >= 0x80 bytes of a UTF-8 sequence, passes through untouched.
+function unescapeToBytes(input) {
+  const buf = toBytes(input);
+  const out = Buffer.allocUnsafe(buf.length);
   let n = 0;
-  for (let i = 0; i < s.length; i++) {
-    const c = s.charCodeAt(i);
-    if (c === 0x5c && i + 3 < s.length) {                       // '\'
-      const oct = s.slice(i + 1, i + 4);
-      if (/^[0-7]{3}$/.test(oct)) { out[n++] = parseInt(oct, 8) & 0xff; i += 3; continue; }
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === BACKSLASH && i + 3 < buf.length && isOct(buf[i + 1]) && isOct(buf[i + 2]) && isOct(buf[i + 3])) {
+      out[n++] = (((buf[i + 1] - 0x30) << 6) | ((buf[i + 2] - 0x30) << 3) | (buf[i + 3] - 0x30)) & 0xff;
+      i += 3;
+      continue;
     }
-    out[n++] = c & 0xff;
+    out[n++] = buf[i];
   }
   return out.subarray(0, n);
 }
@@ -49,51 +76,68 @@ function unescapeToBytes(s) {
  * @param {(paneId: string, text: string) => void} h.onOutput  decoded pane bytes
  * @param {(reason: string) => void} [h.onExit]                %exit seen
  * @param {(lines: string[], isError: boolean) => void} [h.onBlock]  a %begin…%end command reply
- * @returns {{feed: (chunk: string) => void}}
+ * @returns {{feed: (chunk: Buffer|string) => void}}
  */
 function createParser({ onOutput, onExit, onBlock } = {}) {
-  let pending = '';                       // partial line carried between chunks
+  let pending = EMPTY;                    // partial line carried between chunks, as BYTES
   let inBlock = false;
   let block = [];
   const decoders = new Map();             // paneId → StringDecoder, for split multi-byte chars
 
   function line(raw) {
     // The DCS introducer rides in front of the very first line; the terminator can trail the last.
-    let l = raw.replace(/^\x1bP1000p/, '').replace(/\x1b\\$/, '');
+    let l = raw;
+    if (startsWithAscii(l, '\x1bP1000p')) l = l.subarray(DCS.length);
+    if (l.length >= ST.length && l[l.length - 2] === ST[0] && l[l.length - 1] === ST[1]) {
+      l = l.subarray(0, l.length - ST.length);
+    }
     if (inBlock) {
-      if (l.startsWith('%end') || l.startsWith('%error')) {
+      // A command reply is text (it is what tmux printed for `capture-pane` and friends), so it
+      // decodes as UTF-8 in one shot — a reply line always arrives whole.
+      if (startsWithAscii(l, '%end') || startsWithAscii(l, '%error')) {
         inBlock = false;
-        if (onBlock) onBlock(block, l.startsWith('%error'));
+        if (onBlock) onBlock(block, startsWithAscii(l, '%error'));
         block = [];
-      } else block.push(l);
+      } else block.push(l.toString('utf8'));
       return;
     }
-    if (l.startsWith('%begin')) { inBlock = true; block = []; return; }
-    if (l.startsWith('%output ')) {
-      // %output %<pane> <escaped bytes>   — the data may legitimately be empty
-      const m = /^%output (%\d+) ?([\s\S]*)$/.exec(l);
-      if (!m || !onOutput) return;
-      const pane = m[1];
+    if (startsWithAscii(l, '%begin')) { inBlock = true; block = []; return; }
+    if (startsWithAscii(l, '%output ')) {
+      // %output %<pane> <bytes>   — the data may legitimately be empty. The header is pure ASCII,
+      // so it is scanned by byte offset; everything after the separating space is PANE BYTES and is
+      // never treated as text until the decoder below.
+      if (!onOutput) return;
+      let j = 8;                                             // past '%output '
+      if (l[j] !== PCT) return;                              // '%' of the pane id
+      let k = j + 1;
+      while (k < l.length && l[k] >= 0x30 && l[k] <= 0x39) k++;
+      if (k === j + 1) return;                               // no digits — not a pane id
+      const pane = l.subarray(j, k).toString('latin1');
+      const data = l[k] === SPACE ? l.subarray(k + 1) : l.subarray(k);
       let dec = decoders.get(pane);
       if (!dec) { dec = new StringDecoder('utf8'); decoders.set(pane, dec); }
-      const text = dec.write(unescapeToBytes(m[2]));
+      const text = dec.write(unescapeToBytes(data));
       if (text) onOutput(pane, text);
       return;
     }
-    if (l.startsWith('%exit')) { if (onExit) onExit(l.slice(5).trim()); return; }
+    if (startsWithAscii(l, '%exit')) { if (onExit) onExit(l.subarray(5).toString('utf8').trim()); return; }
     // every other %notification (session-changed, window-add, layout-change, …) is not needed here
   }
 
   return {
     feed(chunk) {
-      pending += chunk;
-      let i;
-      while ((i = pending.indexOf('\n')) !== -1) {
-        let l = pending.slice(0, i);
-        pending = pending.slice(i + 1);
-        if (l.endsWith('\r')) l = l.slice(0, -1);
-        line(l);
+      const b = toBytes(chunk);
+      pending = pending.length ? Buffer.concat([pending, b]) : b;
+      // %output data never contains a raw LF — tmux escapes every byte below 0x20 — so splitting
+      // the stream on LF can never cut a frame in half.
+      let start = 0, i;
+      while ((i = pending.indexOf(LF, start)) !== -1) {
+        const end = i > start && pending[i - 1] === CR ? i - 1 : i;
+        line(pending.subarray(start, end));
+        start = i + 1;
       }
+      // Copy the remainder rather than holding a subarray: a subarray pins the whole parent chunk.
+      pending = start >= pending.length ? EMPTY : (start ? Buffer.from(pending.subarray(start)) : pending);
     },
   };
 }

package/workspace/public/app.js

@@ -883,6 +883,8 @@ async function openDoc(pth, kind) {
   body.querySelectorAll('[data-doc]').forEach((a) => a.onclick = (e) => { e.preventDefault(); openDoc(a.dataset.doc); });
   wireImgFallback(body);
   markActiveDoc(pth);
+  // Only a markdown document can be reviewed, and only a document — never a summoned surface.
+  $('docReview').hidden = !(state.docPath && /\.(md|markdown|mdown|mkd|mdx|skill)$/i.test(state.docPath));
   refit();
 }
 function markActiveDoc(pth) {
@@ -929,6 +931,7 @@ function renderHtmlDoc(body, text) {
 }
 function closeDoc() {
   state.docPath = null; state.surface = null;
+  $('docReview').hidden = true;
   $('paneDoc').hidden = true;
   $('railSplit').hidden = true;
   $('docBody').innerHTML = '';
@@ -1807,6 +1810,25 @@ $('themeBtn').onclick = () => {
 };
 $('closeDoc').onclick = closeDoc;
 
+// "review" on an open document. The whole point of putting it HERE is that the scope needs no
+// naming — the thing to review is the thing you are reading. The server assembles the prompt
+// (skill body + resolved paths) because a tenant repo has no workspace/ folder to point at.
+$('docReview').onclick = async () => {
+  const pth = state.docPath;
+  if (!pth) return;
+  const btn = $('docReview');
+  btn.disabled = true; btn.textContent = 'starting…';
+  let out = {};
+  try {
+    out = await (await fetch('/api/review/start', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ws: state.wsId, path: pth }) })).json();
+  } catch { out = { ok: false, error: 'could not reach the workspace server' }; }
+  btn.disabled = false; btn.textContent = 'review';
+  if (!out.ok) { flash(out.error || 'could not start the review'); return; }
+  flash('reviewing ' + pth.split('/').pop() + ' — watch the session');
+  if (out.sessionId) selectSession(out.sessionId);
+};
+
 // ── ⌘K / Ctrl-K jump palette (client-side: workspaces + sessions + initiatives + docs) ──
 // ── on-demand surfaces (Plan · Deliver · Measure · Report) ─────────────────────────────────────
 // Summoned from ⌘K, rendered in the reader, derived through the server's local state adapter and
@@ -1834,6 +1856,7 @@ async function openSurface(name) {
   showRail();
   $('paneDoc').hidden = false; $('railSplit').hidden = false; foldPane('doc', true);
   state.surface = name; state.docPath = null;
+  $('docReview').hidden = true;
   document.querySelectorAll('.doc').forEach((b) => b.classList.remove('on'));
   $('crumb').innerHTML = `<bdi>surface · ${esc(name)}</bdi>`;
   $('docBody').scrollTop = 0;

package/workspace/public/index.html

@@ -187,6 +187,7 @@
         <div class="cap">
           <button class="fold" id="docFold" aria-expanded="true" title="Hide the document"><span class="chev" aria-hidden="true">▾</span>document</button>
           <span class="crumb" id="crumb"></span>
+          <button class="mini docrev" id="docReview" hidden title="Have an agent review this document">review</button>
           <button class="x" id="closeDoc" aria-label="Close document">✕</button>
         </div>
         <div class="pane-body doc-body" id="docBody" tabindex="0"></div>

package/workspace/server.js

@@ -603,7 +603,15 @@ const DELIV_DIR = path.join(STATE, 'deliverables');
 // Reviews the doc-review skill files (workspace-review-and-edit). One JSON per run, written by the
 // skill session, read back by /api/review. Runtime, not the record: the durable artifact of a review
 // is the correction records its dispositions produce, which live in planning/runs/ and are tracked.
-const REVIEW_DIR = path.join(STATE, 'reviews');
+// PER WORKSPACE, like every other piece of state here. An earlier build put this in the SERVER's own
+// state/ — which meant two open repos shared one review pile, and a tenant repo (which has no
+// workspace/ folder at all) had the reviews written into the installed app instead of into the repo
+// being reviewed. Reviews name documents and quote their contents, so that was a cross-workspace leak,
+// not just untidy filing. stateDirFor() is the same resolver needs.json and acceptances.jsonl use.
+function reviewDirFor(w, opts) {
+  const d = stateDirFor(w, opts);
+  return d ? path.join(d, 'reviews') : null;
+}
 // Skills are file-driven (workspace-skill-authoring): built-ins ship committed under workspace/skills/,
 // user-authored ones are scaffolded into state/skills/ by the New Skill flow. There is ONE user-facing
 // concept — a skill — so the picker never exposes the internal `run`/`kind`; how a skill runs (server
@@ -898,9 +906,27 @@ function heartbeat() {
 }
 try { const _hb = setInterval(heartbeat, LIVENESS_MS); if (_hb.unref) _hb.unref(); } catch {}
 
+// Trim the ring from the FRONT at a LINE boundary. A blind slice cuts wherever the byte count
+// lands — which is routinely INSIDE an escape sequence, and the truncated tail then replays as
+// literal rubble ("5;203m") the next time a client attaches and we write the buffer to xterm.js;
+// or BETWEEN the halves of a surrogate pair, and the lone surrogate becomes U+FFFD on the JSON hop
+// to the browser. Neither is recoverable downstream. An escape sequence never spans a newline, so
+// moving the cut forward to just past the next one makes both impossible. If the kept region has no
+// newline near its head (one enormous line) the raw cut stands, stepping off a lone low surrogate.
+const TRIM_SCAN = 8192;                                // how far past the cut to look for a boundary
+function trimBuf(buf, limit) {
+  if (buf.length <= limit) return buf;
+  let cut = buf.length - limit;
+  const nl = buf.indexOf('\n', cut);
+  if (nl !== -1 && nl - cut <= TRIM_SCAN) return buf.slice(nl + 1);
+  const c = buf.charCodeAt(cut);
+  if (c >= 0xdc00 && c <= 0xdfff) cut++;               // never start on a low surrogate
+  return buf.slice(cut);
+}
+
 function appendBuf(s, data) {
   s.buf += data;
-  if (s.buf.length > SCROLLBACK) s.buf = s.buf.slice(s.buf.length - SCROLLBACK);
+  if (s.buf.length > SCROLLBACK) s.buf = trimBuf(s.buf, SCROLLBACK);
   // Parser 2's whole input: the moment output last arrived. `quiet` is derived from this, never
   // from reading the bytes — which is why it is the only one of the five that cannot misread.
   s.lastOutputAt = Date.now();
@@ -1005,7 +1031,7 @@ function seedFromPaneHistory(s, name) {
   if (r.status !== 0 || !r.stdout) return false;
   const text = r.stdout.replace(/\s+$/, '').replace(/\r?\n/g, '\r\n');
   if (!text) return false;
-  s.buf = text + '\r\n';
+  s.buf = trimBuf(text + '\r\n', SCROLLBACK);          // 5000 lines of history can overrun the ring
   s.parsed = null;
   return true;
 }
@@ -1022,8 +1048,14 @@ function attachPty(s, { seed = false } = {}) {
   const startedMs = Date.now();
   let p;
   try {
+    // `encoding: null` is LOAD-BEARING, not a style choice. A control-mode stream is BYTES: tmux
+    // escapes only c < 0x20 and the backslash, so every byte of a UTF-8 sequence rides through raw.
+    // Letting node-pty decode it to a string first and re-narrowing to bytes in the parser destroyed
+    // every non-ASCII character — box drawing became NULs and form feeds, ✓ became 0x13, emoji and
+    // accents became U+FFFD. The parser owns the one and only decode. See lib/tmux-control.js.
     p = pty.spawn(TMUX, ['-L', TMUX_SOCK, '-CC', 'attach-session', '-t', name],
-      { name: 'xterm-256color', cols: s.cols || 80, rows: s.rows || 24, cwd: s.cwd, env: sessionEnv() });
+      { name: 'xterm-256color', cols: s.cols || 80, rows: s.rows || 24, cwd: s.cwd,
+        env: sessionEnv(), encoding: null });
   } catch (e) {
     // A broken node-pty (e.g. a non-executable spawn-helper) throws synchronously here. This must
     // NOT propagate: on the startup first-shell it would crash the whole server and blank the
@@ -1886,13 +1918,14 @@ async function handleRequest(req, res) {
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
     const want = url.searchParams.get('id');
     let files = [];
-    try { files = fs.readdirSync(REVIEW_DIR).filter((f) => f.endsWith('.json')).sort(); } catch {}
+    const rdir = reviewDirFor(w);
+    try { files = rdir ? fs.readdirSync(rdir).filter((f) => f.endsWith('.json')).sort() : []; } catch {}
     if (want && !/^[A-Za-z0-9._-]+$/.test(want)) return json(res, { ok: false, error: 'bad review id' }, 400);
     const pick = want ? `${want}.json` : files[files.length - 1];
     if (!pick || !files.includes(pick)) return json(res, { ok: true, empty: true, reviews: files.length });
 
     let review;
-    try { review = JSON.parse(fs.readFileSync(path.join(REVIEW_DIR, pick), 'utf8')); }
+    try { review = JSON.parse(fs.readFileSync(path.join(rdir, pick), 'utf8')); }
     catch { return json(res, { ok: false, error: `review '${pick}' is unreadable or not valid JSON` }, 500); }
 
     // The SAME contract the write path enforces (R3/R7). A review that fails it is surfaced as an
@@ -1929,6 +1962,60 @@ async function handleRequest(req, res) {
     }));
     return json(res, { ok: true, id: pick.replace(/\.json$/, ''), read: review.read, at: review.at || null, findings, reviews: files.length, stats, reasons: [...correctionRecord.REASONS] });
   }
+  if (p === '/api/review/start' && req.method === 'POST') {
+    // Review THIS document — the trigger that makes the scope implicit instead of typed. The PM is
+    // reading a document; the thing they want reviewed is the thing in front of them.
+    //
+    // The prompt is assembled HERE, not in the browser, for one reason that matters beyond tidiness:
+    // a tenant product repo has no workspace/ folder. Pointing the agent at
+    // `workspace/skills/doc-review.skill` works in PMOS-self and breaks everywhere else, and so does
+    // telling it to write to `workspace/state/reviews/`. The server knows the skill body and the
+    // resolved state directory for THIS workspace, so both travel in the prompt as absolute facts.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const rel = String(body.path || '').trim();
+    if (!rel) return json(res, { ok: false, error: 'no document named' }, 400);
+    const full = path.resolve(w.root, rel);
+    if (!insideRoot(w.root, full)) return json(res, { ok: false, error: 'outside workspace' }, 404);
+    if (preview.previewKind(path.basename(full)) !== 'markdown') {
+      return json(res, { ok: false, error: 'only markdown documents can be reviewed' }, 400);
+    }
+    if (!fs.existsSync(full)) return json(res, { ok: false, error: 'no such document' }, 404);
+
+    const task = loadTasks().find((t) => t.id === 'doc-review');
+    if (!task || !task.prompt) return json(res, { ok: false, error: 'the doc-review skill is not installed' }, 500);
+
+    const rdir = reviewDirFor(w, { create: true });
+    if (!rdir) return json(res, { ok: false, error: 'this workspace has no state directory to file a review into' }, 500);
+    try { fs.mkdirSync(rdir, { recursive: true }); }
+    catch (e) { warnWriteFail('reviews directory', e); return json(res, { ok: false, error: 'could not create the reviews directory' }, 500); }
+
+    // Scope first, so it is the last thing the agent reads before the procedure — and stated as
+    // paths, because "the documents the PM named" is only a rule if something names them.
+    const extra = Array.isArray(body.also) ? body.also.filter((x) => typeof x === 'string').slice(0, 9) : [];
+    const scope = [rel, ...extra];
+    const preamble = [
+      'Review these documents, and only these:',
+      ...scope.map((s) => `  - ${s}`),
+      '',
+      `File the review as JSON into: ${rdir}`,
+      `The needs-you queue for this workspace is: ${needsFileFor(w) || '(none — skip the needs step)'}`,
+      'Both paths are absolute and already exist. Use them exactly; do not guess a workspace/ path.',
+      '',
+      '--- the skill ---',
+      '',
+    ].join('\n');
+
+    const s = spawnSession({ name: 'review: ' + path.basename(rel), agent: task.agent || 'claude',
+      ws: w.id, origin: 'review:' + rel, initialInput: preamble + task.prompt + '\r' });
+    const started = !!(s && s.pty);
+    return json(res, { ok: started, sessionId: s && s.id, scope, sink: rdir,
+      error: started ? undefined : ((s && s.note) || 'could not start the session') });
+  }
   if (p === '/api/review/dispose' && req.method === 'POST') {
     // The ONLY write path this surface has (workspace-review-and-edit R6/R8/R11). The reader was
     // designed around there being none, so every guard here is load-bearing rather than ceremony.
@@ -2210,6 +2297,9 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   // the legacy-scrollback migration, exported so the suite can assert BOTH halves: the tmux
   // client's preamble is stripped, an inner TUI's own alt-screen use is not.
   stripLegacyClientScreen,
+  // the scrollback ring's front trim, exported pure so the suite can assert that a cut never lands
+  // inside an escape sequence or between the halves of a surrogate pair.
+  trimBuf, SCROLLBACK,
   // the liveness heartbeat's guard, exported pure so the "idle machine stays idle" half can be
   // asserted without a server that has no clients (the suite always has both).
   shouldHeartbeat, LIVENESS_MS, TX_REREAD_MS };

package/workspace/skills/doc-review.skill

@@ -56,7 +56,8 @@ and is not — it is a measured open question (`pm-decisions.md` 491–503).
 
 ## Procedure
 
-1. **Take the scope.** Read exactly the documents the PM named. Do not widen it.
+1. **Take the scope.** The documents are listed at the top of this prompt. Read exactly those and
+   do not widen the set — the PM chose them by opening one, not by describing a filter.
    *Done when:* every named path has been read in full, and you can list them.
 
 2. **Find, then cut.** For each document, ask the four questions above. Then remove every candidate
@@ -70,8 +71,10 @@ and is not — it is a measured open question (`pm-decisions.md` 491–503).
    guessing. Where the withheld test fires, propose nothing.
    *Done when:* every finding either carries an exact-match proposal or is explicitly withheld.
 
-4. **File the review.** Pick a run id (`doc-review-<UTC-timestamp>`), then write
-   `workspace/state/reviews/<run-id>.json` with exactly this shape:
+4. **File the review.** Pick a run id (`doc-review-<UTC-timestamp>`). Write it to the reviews
+   directory **named at the top of this prompt** — an absolute path that already exists. Do not
+   guess a `workspace/…` path: a product repo using the PMOS kit has no `workspace/` folder, and
+   inventing one files the review where nothing will read it. The shape:
 
    ```json
    {
@@ -94,11 +97,13 @@ and is not — it is a measured open question (`pm-decisions.md` 491–503).
 
    `withheld` is a required boolean on every finding and is never inferred. A withheld finding sets
    `"proposal": null` and adds `"withheld_reason"`.
-   *Done when:* the file is valid JSON and `GET /api/review` returns `ok: true` for it. If it returns
-   `422`, the contract rejected a finding — fix it; do not file it anyway.
+   *Done when:* the file is valid JSON in the directory the prompt named, and `GET /api/review`
+   returns `ok: true` for it. If it returns `422`, the contract rejected a finding — fix it; do not
+   file it anyway.
 
-5. **Tell the PM it is ready.** Read `workspace/state/needs.json` (a missing file is `[]`), append
-   exactly this object, and write the whole array back — it must stay a valid JSON array:
+5. **Tell the PM it is ready.** Read the needs-you queue **named at the top of this prompt** (a
+   missing file is `[]`), append exactly this object, and write the whole array back — it must stay
+   a valid JSON array. If the prompt said there is none, skip this step:
 
    ```json
    {"run_id":"<run-id>","kind":"review","initiative_id":"workspace-review-and-edit","question":"Document review — <n> findings"}