create-pmos 0.31.0 → 0.32.0

package/workspace/lib/sink.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+'use strict';
+/* sink.js — the ONE place the append-only ledger discipline lives.
+ *
+ * ── WHY THIS FILE EXISTS ────────────────────────────────────────────────────────────────────────
+ * `record-eval.js` was PMOS's first validated writer. Three independent passes found four defects in
+ * it, and all four were fixed IN THAT FILE:
+ *
+ *   1. the sink was a caller-supplied allowlist   -> a caller could name its own destination
+ *   2. the file was opened before validation      -> N refused writes leaked N descriptors to EMFILE
+ *   3. a refused write still created the sink     -> refusing to write left the file behind
+ *   4. the symlink check was a path-level stat    -> a hardlink walked straight through it
+ *
+ * Two writers built afterwards inherited the fixes BY HAND, and each inheritance read as evidence
+ * that the pattern was holding. It was not holding — it was propagating FORWARD ONLY. The two
+ * writers that already existed when the defects were found were never revisited, because the process
+ * asks "does the new thing follow the rule?" and never "where else does this rule already live?"
+ *
+ * Measured by attempted write on 2026-08-04:
+ *
+ *   scripts/work-item.js     -> wrote 198 bytes through a symlink into a decoy
+ *   scripts/verify-queue.js  -> the same, AND wrote 202 bytes into a fresh tmpdir, because its
+ *                               allowlist compared `path.basename` alone. A basename is not a
+ *                               location; every directory on disk has one.
+ *
+ * Both are merged, PM-accepted, and load-bearing for D65 steps 1 and 2. So the discipline moves here
+ * and the writers call it. One wrong place that every assertion points at beats five where three
+ * happen to be right.
+ *
+ * ── THE RULE, STATED ONCE ───────────────────────────────────────────────────────────────────────
+ *   Resolve before allowing.  Validate before opening.  Write to the descriptor that was vetted.
+ *
+ * The third clause is the one that looks redundant and is not. A path checked and then re-opened by
+ * path is two operations on two objects: whatever was approved may not be what gets written. The fd
+ * IS the approval, so it is what the caller must be handed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * THE `ForbiddenWrite`. One class, exported, re-exported by every writer that uses this guard.
+ *
+ * There were five of these — one per writer that had a guard at all — and that is not a cosmetic duplication. Callers and
+ * assertions tell "refused on purpose" from "crashed" with `instanceof`, so a guard throwing its own
+ * private copy makes every one of those checks silently false: `scripts/tests/work-item.sh` reported
+ * `threw ForbiddenWrite, want ForbiddenWrite` on seventeen assertions the moment this module started
+ * throwing a second class with the same name. A refusal nobody can recognise as a refusal is not one.
+ *
+ * `detail` is always set (null when absent) rather than conditionally attached, because a property
+ * that sometimes exists is a second shape for callers to handle.
+ */
+class ForbiddenWrite extends Error {
+  constructor(message, detail) {
+    super(message);
+    this.name = 'ForbiddenWrite';
+    this.detail = detail || null;
+  }
+}
+
+/** Resolve a path through its real directory. Kept separate so the sink and the target are compared
+ *  the same way — comparing a resolved target against an unresolved sink is a mismatch by
+ *  construction, and would refuse every legitimate write on a machine where /tmp is a symlink. */
+function resolveThrough(p) {
+  return path.join(fs.realpathSync(path.dirname(path.resolve(p))), path.basename(p));
+}
+
+/**
+ * Build a guard bound to ONE sink.
+ *
+ * @param {object} spec
+ * @param {string} spec.sink     absolute path of the only file this guard will ever open.
+ * @param {string} spec.what     noun for error messages, e.g. 'work-item events'.
+ * @returns {{ open: function, sinkPath: function, __setSinkForTests: function }}
+ *
+ * The sink is a CONSTRUCTION-TIME constant, never an argument to `open`. That is defect 1 of the
+ * original four, and re-admitting it as "just a parameter" is how it would come back.
+ */
+function createSinkGuard(spec) {
+  if (!spec || typeof spec.sink !== 'string' || !spec.sink) {
+    throw new ForbiddenWrite('a sink guard needs a declared `sink` path — refused (fail-closed)');
+  }
+  const what = spec.what || 'records';
+  const declared = spec.sink;
+  let overrideForTests = null;
+
+  /* A seam, not a door. Gated so it cannot be reached in a production process even if something
+   * calls it — the point of A4 is that no code path lets a caller choose the destination. */
+  function __setSinkForTests(p) {
+    /* An explicit allowed set. `!process.env.PMOS_TEST` treats the STRING '0' as truthy, so
+     * PMOS_TEST=0 — the natural way an operator turns test mode OFF — OPENED the production sink
+     * override instead of closing it. A flag whose "off" value means "on" is worse than no flag. */
+    const on = (v) => v === '1' || v === 'true' || v === 'yes';
+    if (process.env.NODE_ENV !== 'test' && !on(process.env.PMOS_TEST)) {
+      throw new ForbiddenWrite('__setSinkForTests is a test seam — set NODE_ENV=test or PMOS_TEST=1 to use it');
+    }
+    overrideForTests = p;
+  }
+
+  const sinkPath = () => overrideForTests || declared;
+
+  /**
+   * Pre-flight: validate the record and confirm the target RESOLVES to the sink — without opening
+   * anything. For callers that want to ask "would this be permitted?" without a side effect.
+   *
+   * NOT AUTHORITATIVE, and the gap is deliberate rather than an oversight. Whether the sink is a
+   * symlink or carries a second hard link cannot be established without a descriptor, and a `lstat`
+   * here would answer about a path that may differ from the file eventually opened — which is the
+   * check-then-write race this module exists to close. `open` is the authority; this is a courtesy.
+   * The suite asserts the difference: a symlinked sink passes `check` and is refused by `open`.
+   */
+  function check(targetPath, validate) {
+    if (typeof targetPath !== 'string' || !targetPath) {
+      throw new ForbiddenWrite(`no target path supplied for ${what} — refused (fail-closed)`);
+    }
+    if (typeof validate === 'function') {
+      const v = validate();
+      if (!v || !v.ok) {
+        const errs = (v && v.errors) || ['invalid'];
+        throw new ForbiddenWrite(`invalid ${what} — refused: ${errs.join('; ')}`, { errors: errs });
+      }
+    }
+    let resolved;
+    try { resolved = resolveThrough(targetPath); }
+    catch { throw new ForbiddenWrite(`the sink directory does not resolve for '${targetPath}' — refused (fail-closed)`); }
+    let sinkResolved = sinkPath();
+    try { sinkResolved = resolveThrough(sinkPath()); } catch { /* not created yet */ }
+    if (resolved !== sinkResolved) {
+      throw new ForbiddenWrite(
+        `${what} are written only to ${sinkResolved}; '${targetPath}' resolves to '${resolved}'`,
+        { targetPath, resolved, sink: sinkResolved });
+    }
+    return true;
+  }
+
+  /**
+   * Vet `targetPath` against the declared sink and return a descriptor open for append.
+   *
+   * The caller MUST close it. Everything that can refuse, refuses before the file is opened, so a
+   * refusal creates nothing and leaks nothing.
+   *
+   * @param {string} targetPath   where the caller believes it is writing.
+   * @param {function} [validate] returns { ok, errors } — runs BEFORE the open (defects 2 and 3).
+   * @returns {number} a vetted file descriptor.
+   */
+  function open(targetPath, validate) {
+    if (typeof targetPath !== 'string' || !targetPath) {
+      throw new ForbiddenWrite(`no target path supplied for ${what} — refused (fail-closed)`);
+    }
+
+    /* BEFORE the open. Ordering is the whole of defects 2 and 3: validating after opening leaks a
+     * descriptor per refusal, and O_CREAT means the refused write has already made the file. */
+    if (typeof validate === 'function') {
+      const v = validate();
+      if (!v || !v.ok) {
+        const errs = (v && v.errors) || ['invalid'];
+        throw new ForbiddenWrite(`invalid ${what} — refused: ${errs.join('; ')}`, { errors: errs });
+      }
+    }
+
+    let resolved;
+    try {
+      resolved = resolveThrough(targetPath);
+    } catch {
+      throw new ForbiddenWrite(`the sink directory does not resolve for '${targetPath}' — refused (fail-closed)`);
+    }
+    let sinkResolved = sinkPath();
+    try { sinkResolved = resolveThrough(sinkPath()); } catch { /* not created yet — compare literally */ }
+
+    /* A RESOLVED comparison, not a basename one. `verify-queue.js` compared basenames and therefore
+     * accepted every directory on disk that happened to contain the right filename. */
+    if (resolved !== sinkResolved) {
+      throw new ForbiddenWrite(
+        `${what} are written only to ${sinkResolved}; '${targetPath}' resolves to '${resolved}'`,
+        { targetPath, resolved, sink: sinkResolved });
+    }
+
+    let fd;
+    try {
+      fd = fs.openSync(
+        resolved,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND
+          | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK,
+        0o644);
+    } catch (e) {
+      /* O_NOFOLLOW turns "the sink is a symlink" into ELOOP here rather than a silent write to
+       * wherever it pointed. That is defect 4, and it is refused at open rather than by a stat that
+       * a hardlink does not answer.
+       *
+       * O_NONBLOCK is not about performance. Opening a FIFO for writing BLOCKS until a reader
+       * arrives, so a named pipe left at the sink path hangs the writer forever — found by the
+       * assertion below, which hung this suite past its timeout instead of failing. A refusal that
+       * never returns is worse than a wrong answer: nothing reports it and nothing times it out.
+       * With O_NONBLOCK the same case returns ENXIO immediately and lands in the refusal path, and
+       * on a regular file the flag does nothing at all. */
+      throw new ForbiddenWrite(
+        `cannot open the ${what} ledger at '${targetPath}' safely (${e.code || e.message}) — refused (fail-closed)`,
+        { code: e.code });
+    }
+
+    try {
+      /* fstat on the FD, not stat on the path: for the FINAL component this genuinely closes the
+       * check-then-open race — an independent pass swapped the target inside the resolve→open window
+       * with perfect timing and got ELOOP, nlink=2 and a refusal every time.
+       *
+       * It does NOT cover the PARENT directory. `resolveThrough` realpaths the directory and
+       * `openSync` then re-walks that resolved path, so a local process able to rename the sink's
+       * parent and drop a directory symlink in its place inside that window can redirect the append
+       * — measured, 195 bytes into a foreign directory. That needs a concurrently-racing local
+       * attacker with write access to the parent, a strictly larger capability than the symlink
+       * defect this module was built to fix, so it is stated rather than claimed away. Closing it
+       * properly needs openat-style descent, which Node does not expose. The header's "the fd IS the
+       * approval" is true of the file, not of the path walked to reach it. */
+      const st = fs.fstatSync(fd);
+      if (!st.isFile()) {
+        throw new ForbiddenWrite(`'${targetPath}' is not a regular file — refused (fail-closed)`);
+      }
+      if (st.nlink !== 1) {
+        throw new ForbiddenWrite(
+          `'${targetPath}' has ${st.nlink} hard links; a ledger with a second name is not one this ` +
+          'writer controls — refused (fail-closed)', { nlink: st.nlink });
+      }
+    } catch (e) {
+      fs.closeSync(fd);
+      throw e;
+    }
+
+    return fd;
+  }
+
+  /**
+   * The whole write, start to finish: vet, append one JSON line, close. Callers should prefer this
+   * over `open` — it is the shape that cannot forget to close, and every existing writer's append is
+   * exactly one line.
+   */
+  function appendLine(targetPath, record, validate) {
+    const fd = open(targetPath, validate);
+    const line = JSON.stringify(record) + '\n';
+    const want = Buffer.byteLength(line);
+    try {
+      /* THE RETURN VALUE IS NOT OPTIONAL. This was `fs.writeSync(fd, line)` with the result
+       * discarded, which reports a SHORT WRITE as success. Forced on a 64K tmpfs: a normal-shaped
+       * record returned true having appended a 3901-byte fragment with no trailing newline, and the
+       * next append CONCATENATED onto it — so one ENOSPC destroys two records and leaves a single
+       * line that no reader can parse. This is the append-only system of record, every reader
+       * JSON.parses line by line, and all six writers route through this one call.
+       *
+       * Loop, because a partial write is not necessarily an error — then verify the total. A torn
+       * tail is worse than a refused write, so if the bytes did not all land, say so loudly rather
+       * than returning true over a corrupted ledger. */
+      /* The size BEFORE this append, taken from the vetted fd. This is what makes the failure path a
+       * real refusal instead of a report: if the write tears, the file is truncated back to here and
+       * the ledger is left exactly as it was found. `nlink === 1` was already proven above, so no
+       * other name for this file exists and the rollback cannot reach anyone else's data. */
+      const before = fs.fstatSync(fd).size;
+      const buf = Buffer.from(line, 'utf8');
+      let written = 0;
+      let cause = null;
+      try {
+        while (written < want) {
+          const n = fs.writeSync(fd, buf, written, want - written);
+          if (!(n > 0)) break;           // no progress: stop rather than spin
+          written += n;
+        }
+      } catch (e) {
+        /* ENOSPC does NOT arrive as a short write. Measured on a full tmpfs: the first writeSync
+         * short-writes 376 of 440 bytes with no error and the SECOND one throws — so a version that
+         * only checked `written !== want` never reached its own error path, and a raw Error escaped
+         * with name 'Error'. Everything in this repo tells a deliberate refusal from a crash with
+         * `instanceof ForbiddenWrite` (workspace/test.js:1772 checks e.name), so an unwrapped throw
+         * on the worst outcome this module has is the one place that signal must not be missing. */
+        cause = e;
+      }
+
+      if (cause || written !== want) {
+        /* THE ROLLBACK MUST NOT DESTROY SOMEONE ELSE'S RECORD, and the first version did.
+         *
+         * It called ftruncateSync(fd, before) unconditionally. `before` was measured at the top of
+         * this function, so ANY append by another process in between — a complete, successful,
+         * returned-true append — was inside the range being truncated away. Measured by an
+         * independent pass across 5 of 5 rounds: records whose write returned `true` were missing
+         * from disk afterwards, and the ledger was NUL-padded. A rollback that eats a committed
+         * record is worse than the torn line it was added to prevent.
+         *
+         * O_APPEND makes the arithmetic decidable: our bytes are the last `written` of the file if
+         * and only if nobody else appended. So truncate ONLY when the file is exactly the size our
+         * own write would have made it. Otherwise the tail is not ours to remove, and the honest
+         * outcome is to say the ledger is torn rather than to fix it by deleting a stranger's data. */
+        let rolledBack = false;
+        let intervened = false;
+        try {
+          const now = fs.fstatSync(fd).size;
+          if (now === before + written) { fs.ftruncateSync(fd, before); rolledBack = true; }
+          else intervened = true;          // another writer appended; the tail is not ours
+        } catch { /* reported below */ }
+
+        const detail = { written, want, before, rolledBack, intervened, code: cause && cause.code };
+        throw new ForbiddenWrite(
+          `partial append to the ${what} ledger: ${written} of ${want} bytes landed` +
+          (cause ? ` (${cause.code || cause.message})` : '') + '. ' +
+          (rolledBack
+            ? 'The ledger was truncated back to its pre-write size, so nothing was written and the ' +
+              'next append will not concatenate onto a fragment.'
+            : intervened
+              ? 'NOT ROLLED BACK ON PURPOSE — another writer appended while this write was failing, ' +
+                'so the bytes at the end of the file are not this one\'s to remove. The ledger holds ' +
+                'a torn fragment that must be repaired by hand; truncating it here would have ' +
+                'deleted a record that committed successfully.'
+              : 'THE ROLLBACK ALSO FAILED — the ledger now ends in a torn line with no trailing ' +
+                'newline, and the next append WILL concatenate onto it, destroying a second record. ' +
+                'Repair it by hand before writing again.'),
+          detail);
+      }
+    } finally { fs.closeSync(fd); }
+    return true;
+  }
+
+  return { check, open, appendLine, sinkPath, __setSinkForTests };
+}
+
+module.exports = { createSinkGuard, ForbiddenWrite, resolveThrough };

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "private": true,
-  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

package/workspace/public/index.html

@@ -53,6 +53,10 @@
      opinion about what an .html file is would mean the endpoint and the pane disagreeing about the
      same document. Classic script (a UMD), like the three above. -->
 <script src="/lib/preview-kind.js"></script>
+<!-- The newline normalizer behind the doc tab's `normalize` action (markdown-newlines). The same
+     file scripts/md-newlines.js requires, loaded here as window.MdNormalize, so the one-click
+     repair and the CI ratchet can never disagree about what a normalized document is. -->
+<script src="/lib/md-normalize.js"></script>
 <link rel="preload" href="/vendor/ibm-plex-mono-500.woff2" as="font" type="font/woff2" crossorigin />
 </head>
 <body>

package/workspace/public/pm/tab-doc.js

@@ -316,6 +316,7 @@ function diffBody(tab, raw, text, dirty) {
 /* ── per-tab state that is DOM, not data ───────────────────────────────────────────────────── */
 
 const boxes = new Map();      // tab id -> the persistent textarea for that tab
+const normNote = new Map();   // tab id -> what the last `normalize` click did, in words
 
 function editBox(tab) {
   let ta = boxes.get(tab.id);
@@ -336,6 +337,7 @@ function editBox(tab) {
 /** Release what a closed doc tab held. Called by panel-tabs.js when the tab goes away. */
 export function disposeDoc(id) {
   boxes.delete(id);
+  normNote.delete(id);
   frames.delete(id);
   scrollers.delete(id);
 }
@@ -373,15 +375,44 @@ export function mountDoc(host, tab) {
     hover: 'border-color:var(--ring)',
   }, 'revert') : null;
 
+  /* ── normalize ────────────────────────────────────────────────────────────────────────────────
+   * The one-click half of markdown-newlines. It writes the normalized text into the BUFFER, never
+   * to disk: the pane goes dirty, `diff` shows exactly which lines were joined, and `save` is the
+   * existing write path with its existing refusal on a changed base. So a repair the PM did not
+   * want is one `revert` away, and no new way to write a file was added to get it.
+   *
+   * A document that is already normalized reports that and leaves the buffer alone — marking a
+   * clean file dirty for nothing is how a tool teaches you to ignore its dirty flag. */
+  const norm = typeof window !== 'undefined' ? window.MdNormalize : null;
+  const canNormalize = !!(norm && typeof norm.normalize === 'function')
+    && !isHtmlDoc(tab.path) && !isReference(tab.path) && !unread.has(tab.path);
+  const normBtn = canNormalize ? el('button', {
+    onClick: () => {
+      const r = norm.normalize(text);
+      normNote.set(tab.id, r.changed
+        ? r.joins + ' line(s) joined' + (r.blanks ? ', ' + r.blanks + ' blank inserted' : '')
+        : 'already normalized — every paragraph is one line');
+      if (!r.changed) { setState({}); return; }
+      setState((s) => ({ docEdits: { ...s.docEdits, [tab.path]: r.text } }));
+    },
+    style: 'margin-left:8px;font-family:var(--mono);font-size:10.5px;padding:4px 10px;min-height:26px;background:var(--secondary);border:1px solid var(--border);color:var(--muted-foreground)',
+    hover: 'border-color:var(--ring)',
+    title: 'Join hard-wrapped paragraphs into one line each — what a Jira issue, a Google Doc or any'
+      + ' plain-text destination needs. Writes the buffer, not the file: read it in diff, then save.',
+  }, 'normalize') : null;
+
   // The one place a real-mode refusal is reported: the same line that carries the dirty flag, so
-  // a save that did not happen cannot read as one that did.
-  const dirtyLabel = err ? 'not saved — ' + err : (dirty ? '● modified — unsaved' : 'saved on disk');
+  // a save that did not happen cannot read as one that did. The normalize note shares the line for
+  // the same reason — a repair that changed nothing must say so where the PM is already looking.
+  const note = normNote.get(tab.id);
+  const dirtyLabel = err ? 'not saved — ' + err
+    : (dirty ? '● modified — unsaved' : (note || 'saved on disk'));
   const dirtyColor = err ? 'var(--destructive)' : (dirty ? 'var(--warning)' : 'var(--muted-foreground)');
 
   const modeBar = el('div', {
     style: 'flex:none;display:flex;gap:2px;align-items:center;padding:6px 10px;border-bottom:1px solid var(--border);background:var(--background)',
   },
-    modeBtns, saveBtn, revertBtn,
+    modeBtns, normBtn, saveBtn, revertBtn,
     el('span', { style: 'margin-left:auto;font-family:var(--mono);font-size:10px;color:' + dirtyColor }, iv(dirtyLabel)),
   );
 

package/workspace/server.js

@@ -61,6 +61,7 @@ function ensureSpawnHelperExecutable() {
 ensureSpawnHelperExecutable();
 
 const { checkSurface } = require('./lib/surface-contract');
+const { createSinkGuard } = require('./lib/sink.js');
 const scheduleLogic = require('./lib/schedule-logic');
 const harness = require('./lib/harness-parse');
 const transcript = require('./lib/transcript-read');
@@ -3760,6 +3761,10 @@ async function handleRequest(req, res) {
   // /pm/ module graph below, and one front end is the point. A stray <script src="/app.js"> now
   // 404s loudly rather than silently resurrecting a second, diverging surface.
   if (p === '/lib/preview-kind.js') return serveFile(res, path.join(__dirname, 'lib', 'preview-kind.js'));
+  // The newline normalizer the doc tab's `normalize` action runs, and the same file
+  // scripts/md-newlines.js requires — one implementation, so the button and the gate can never
+  // disagree about what a normalized document is (markdown-newlines).
+  if (p === '/lib/md-normalize.js') return serveFile(res, path.join(__dirname, 'lib', 'md-normalize.js'));
   if (p === '/lib/layout.js') return serveFile(res, path.join(__dirname, 'lib', 'layout.js'));
   if (p === '/lib/mobile-nav.js') return serveFile(res, path.join(__dirname, 'lib', 'mobile-nav.js'));
   if (p === '/lib/session-state.js') return serveFile(res, path.join(__dirname, 'lib', 'session-state.js'));
@@ -4674,9 +4679,25 @@ async function handleRequest(req, res) {
     // A swallowed append + {ok:true} would light the gate green over a record that never landed —
     // exactly the false-green class D64 exists to delete. On write failure return HTTP 500 and
     // {ok:false}, and do NOT report success. The error text carries no header/secret content (D08).
+    /* THROUGH THE GUARD, not a bare append.
+     *
+     * This was `fs.appendFileSync(sink, ...)`. An independent pass attacked it through this very
+     * endpoint's write path: **42 bytes landed through a symlink and it returned {ok:true}**. And
+     * 37 of 49 live acceptance rows carry a `workspace` key that only THIS endpoint writes — so the
+     * guarded writer (scripts/record-acceptance.js) was the one nothing used, while the unguarded
+     * one had written three quarters of the system of record.
+     *
+     * The guard is constructed per resolved sink rather than as one module constant, because the
+     * acceptance ledger legitimately moves with the workspace — kit layout, or the install's own
+     * state/ on fallback. The allowlist therefore degenerates here (target === declared by
+     * construction) and that is stated rather than glossed: what this buys is O_NOFOLLOW, the
+     * `nlink === 1` check, and the torn-append rollback, which is precisely the attack that landed.
+     *
+     * `pm_label` is NOT validated against record-acceptance.js's stricter schema: that writer
+     * REQUIRES the label, this surface must not, and requiring it here would block the PM's click. */
     try {
       if (fallback) fs.mkdirSync(LEGACY_STATE, { recursive: true });   // the install's state/ may not exist yet
-      fs.appendFileSync(sink, JSON.stringify(rec) + '\n');
+      createSinkGuard({ sink, what: 'PM acceptances' }).appendLine(sink, rec);
     } catch (e) {
       warnWriteFail('acceptances.jsonl (Acceptance Gate — system of record)', e);
       return json(res, { ok: false, error: 'could not record the acceptance — the file-mode system of record is unwritable; the decision was NOT saved', sink, fallback }, 500);