session-orchestrator 5.4.0 → 5.5.0

package/scripts/lib/learnings/io.mjs

@@ -14,12 +14,14 @@ import {
   copyFile,
   readdir,
   unlink,
+  open,
 } from 'node:fs/promises';
 import { existsSync, realpathSync } from 'node:fs';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { withFileLock } from '../file-lock.mjs';
+import { digestSha256 } from '../crypto-digest-utils.mjs';
 import {
   validateLearning,
   normalizeLearning,
@@ -219,26 +221,69 @@ function serializeLearningLineChecked(validated, { legacyTolerant = false } = {}
 /**
  * Read all learnings from the given JSONL path. Returns normalized entries
  * (missing extended fields are defaulted). Malformed lines are skipped with
- * their raw text preserved in the result's `malformed` array.
+ * their raw text preserved in the result's `malformed` array, and their
+ * 1-based line numbers in `malformedLineNumbers` (same order).
  *
  * @param {string} filePath — absolute or project-relative path to learnings.jsonl
- * @returns {Promise<{entries: object[], malformed: string[]}>}
+ * @returns {Promise<{entries: object[], malformed: string[], malformedLineNumbers: number[]}>}
  */
 export async function readLearnings(filePath) {
-  if (!existsSync(filePath)) return { entries: [], malformed: [] };
-  const raw = await readFile(filePath, 'utf8');
-  const lines = raw.split('\n').filter((l) => l.length > 0);
+  if (!existsSync(filePath)) return { entries: [], malformed: [], malformedLineNumbers: [] };
+  return parseLearningsText(await readFile(filePath, 'utf8'));
+}
+
+/**
+ * Read a learnings store together with its generation token (#1486), both
+ * from ONE read, so the token describes exactly the records returned.
+ *
+ * The token is `sha256:<hex>` over the file's full text: any append, rewrite
+ * or sweep changes it. An absent store reads as empty text — zero records
+ * either way, so the two states share a token.
+ *
+ * @param {string} filePath
+ * @returns {Promise<{entries: object[], malformed: string[], malformedLineNumbers: number[],
+ *   generation: string}>}
+ */
+export async function readLearningsSnapshot(filePath) {
+  const raw = existsSync(filePath) ? await readFile(filePath, 'utf8') : '';
+  return { ...parseLearningsText(raw), generation: `sha256:${digestSha256(raw)}` };
+}
+
+/**
+ * Parse learnings JSONL text — the line parser behind {@link readLearnings},
+ * exported for callers that must split a header off the text first.
+ *
+ * A blank line — empty, whitespace-only, or a lone `\r` from a CRLF blank line
+ * — carries no record and is skipped, never counted as malformed: malformed
+ * lines are kept verbatim by every rewrite and WARNed on every close, so a
+ * stray blank would otherwise be reported forever (#1489).
+ *
+ * A line that parses but is not a JSON object (`null`, `42`, `[]`, `"x"`) is
+ * malformed too (#1500): `normalizeLearning` turned it into a record of
+ * defaults alone, and every rewrite wrote that invented record back.
+ *
+ * @param {string} raw
+ * @returns {{entries: object[], malformed: string[], malformedLineNumbers: number[]}}
+ *   `malformedLineNumbers[i]` is the 1-based line of `malformed[i]` in `raw`
+ */
+export function parseLearningsText(raw) {
   const entries = [];
   const malformed = [];
-  for (const line of lines) {
+  const malformedLineNumbers = [];
+  raw.split('\n').forEach((line, i) => {
+    if (line.trim().length === 0) return;
     try {
       const parsed = JSON.parse(line);
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new TypeError('not a JSON object');
+      }
       entries.push(normalizeLearning(parsed));
     } catch {
       malformed.push(line);
+      malformedLineNumbers.push(i + 1);
     }
-  }
-  return { entries, malformed };
+  });
+  return { entries, malformed, malformedLineNumbers };
 }
 
 // ---------------------------------------------------------------------------
@@ -263,6 +308,11 @@ export async function readLearnings(filePath) {
  * that landed between a rewriter's read and its rename was silently lost.
  * Validation runs first, outside the lock — a rejected record never waits.
  *
+ * A store whose last line is torn (a crash mid-append left no trailing
+ * newline) gets a `\n` written first, inside the same append: without it the
+ * new record fused onto the torn text into ONE unparseable line, and no reader
+ * ever saw the record (#1489).
+ *
  * @param {string} filePath
  * @param {object} entry
  * @param {{ lockTimeoutMs?: number }} [opts] — store-lock wait, default
@@ -296,13 +346,46 @@ export async function appendLearning(filePath, entry, { lockTimeoutMs } = {}) {
   // parses back AND re-validates before any append touches disk. Throws
   // ValidationError on a non-round-tripping record — file is left untouched.
   const line = serializeLearningLineChecked(validated);
-  // The lock path resolution creates the parent directory.
-  await withLearningsLock(filePath, () => appendFile(filePath, line, 'utf8'), {
-    timeoutMs: lockTimeoutMs,
-  });
+  // The lock path resolution creates the parent directory. The torn-tail check
+  // reads inside the lock, so no other writer can change the tail in between.
+  await withLearningsLock(
+    filePath,
+    async () => {
+      const lead = (await endsWithoutNewline(filePath)) ? '\n' : '';
+      await appendFile(filePath, lead + line, 'utf8');
+    },
+    { timeoutMs: lockTimeoutMs }
+  );
   return validated;
 }
 
+/**
+ * True when `filePath` is a non-empty file whose last byte is not `\n`. An
+ * absent file is `false` (the append creates it). Reads one byte, so the cost
+ * does not grow with the store.
+ *
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+async function endsWithoutNewline(filePath) {
+  let fh;
+  try {
+    fh = await open(filePath, 'r');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false;
+    throw err;
+  }
+  try {
+    const { size } = await fh.stat();
+    if (size === 0) return false;
+    const buf = Buffer.alloc(1);
+    await fh.read(buf, 0, 1, size - 1);
+    return buf[0] !== 0x0a;
+  } finally {
+    await fh.close();
+  }
+}
+
 /**
  * Number of `${basename}.bak-<ISO>` siblings retained after a backup rotation.
  * The atomic rewrite is destructive on a gitignored store (no VCS restore), so
@@ -423,17 +506,35 @@ async function rotateBackups(dir, baseName, keep = BACKUP_KEEP) {
  *   `NaN`) is still caught by the #662 checked serializer regardless of this
  *   flag — see {@link serializeLearningLineChecked}. Pass `false` to restore
  *   the fully-strict behaviour from before EventDrop #386.
+ * - `malformedLines` (#1489): raw text of store lines that did not parse —
+ *   the `malformed` array {@link readLearnings} returns. Written back
+ *   verbatim, one per line, AFTER the validated records. A round-trip writer
+ *   that rewrites from parsed entries alone deletes every such line with no
+ *   archive record (only the keep-3 `.bak` still holds it). OMITTED (the
+ *   default), the store's OWN malformed lines are re-read under the lock and
+ *   kept — so a caller that forgets this option no longer deletes them
+ *   (`export-hw-learnings` did). Pass an array to write exactly those lines;
+ *   `[]` is the explicit opt-out that drops them. Each entry must be a
+ *   non-empty string without a newline; anything else throws a TypeError
+ *   before any disk access, dry run included.
  *
  * @param {string} filePath
  * @param {object[]} entries
- * @param {{dryRun?: boolean, backup?: boolean, legacyTolerant?: boolean}} [opts]
+ * @param {{dryRun?: boolean, backup?: boolean, legacyTolerant?: boolean, malformedLines?: string[]}} [opts]
  * @returns {Promise<object[]>} validated entries (always returned, even dryRun)
  */
 export async function rewriteLearnings(
   filePath,
   entries,
-  { dryRun = false, backup = true, legacyTolerant = true } = {}
+  { dryRun = false, backup = true, legacyTolerant = true, malformedLines } = {}
 ) {
+  if (
+    malformedLines !== undefined &&
+    (!Array.isArray(malformedLines) ||
+      malformedLines.some((l) => typeof l !== 'string' || l.length === 0 || l.includes('\n')))
+  ) {
+    throw new TypeError('rewriteLearnings: malformedLines must be an array of non-empty single-line strings');
+  }
   const validated = entries.map((e) =>
     validateLearning(
       {
@@ -454,12 +555,20 @@ export async function rewriteLearnings(
   // rewrite, no backup — and hand the validated entries back to the caller.
   if (dryRun) return validated;
 
-  const body = lines.join('');
-
   // Under the store lock (#1447 point 8) so no append lands between the backup
   // and the rename. The CALLER's read must sit inside the same lock for a
   // read-modify-write to be safe — this call joins it reentrantly.
   await withLearningsLock(filePath, async () => {
+    // Default: the store's own malformed lines as they stand right now, read
+    // under the lock that guards the rename below.
+    const kept =
+      malformedLines ??
+      (existsSync(filePath) ? parseLearningsText(await readFile(filePath, 'utf8')).malformed : []);
+    // Malformed lines last, each newline-terminated: a truncated final line
+    // otherwise fuses with the next append into one more unparseable line.
+    const body = lines.join('') + kept.map((l) => `${l}\n`).join('');
+
+
     // Backup-before-rewrite (#721): snapshot the current store to a timestamped
     // sidecar BEFORE the destructive rename, then prune to keep-N. Only meaningful
     // when the target already exists (a first-time write has nothing to lose).

package/scripts/lib/lock-reaper.mjs

@@ -66,7 +66,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { enumerateCandidates } from './dispatcher/enumerate.mjs';
-import { readLock, isLockLive, isPidAliveOnHost, LOCK_PATH, DEFAULT_TTL_HOURS } from './session-lock.mjs';
+import { readLock, isLockLive, isPidAliveOnHost, LOCK_PATH, DEFAULT_TTL_HOURS, FUTURE_HEARTBEAT_TOLERANCE_MS } from './session-lock.mjs';
 import { emitEvent } from './events.mjs';
 import { hostnamesMatch, lockHostCandidate } from './host-identity.mjs';
 
@@ -109,21 +109,42 @@ function lockPathFor(repoRoot) {
 }
 
 /**
- * Fractional hours since a lock's last heartbeat (the liveness basis). Falls
- * back to started_at when last_heartbeat is absent (v1 lock). Returns null when
- * neither parses.
+ * Fractional hours since a lock's last heartbeat — the figure the reaper
+ * REPORTS (candidate list `ageHours`, `orchestrator.session.lock.reaped`
+ * `age_hours`). Display only: the reap decision is `isLockLive()`.
+ *
+ * Reads `last_heartbeat` only, like `isLockLive()` since the #595 sunset
+ * (2026-10-02). A lock without one has no heartbeat age, so this returns
+ * `null` (the CLI renders "unknown age") instead of passing off the age since
+ * `started_at` as heartbeat staleness.
  *
  * @param {object} lock
  * @param {number} nowMs
- * @returns {number|null}
+ * @returns {number|null} null when `last_heartbeat` is absent or unparseable.
  */
 function ageHoursOf(lock, nowMs) {
-  const hb = (typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0)
-    ? lock.last_heartbeat
-    : lock.started_at;
-  const ms = Date.parse(hb);
+  if (typeof lock.last_heartbeat !== 'string' || lock.last_heartbeat.length === 0) return null;
+  const ms = Date.parse(lock.last_heartbeat);
   if (Number.isNaN(ms)) return null;
-  return Number(((nowMs - ms) / (3600 * 1000)).toFixed(2));
+  const hours = futureSafeAgeHours(ms, nowMs);
+  return hours === null ? null : Number(hours.toFixed(2));
+}
+
+/**
+ * Hours from `ms` to `nowMs`, or `null` when `ms` lies further in the future
+ * than {@link FUTURE_HEARTBEAT_TOLERANCE_MS} (#1505.2). Such a stamp measures
+ * no age, and a negative one is worse than none: it reads as "younger than
+ * every TTL" and was emitted as a negative `age_hours`. `null` — not 0 — so an
+ * unmeasurable age never looks like a fresh one. Within the tolerance (clock
+ * skew) the age clamps to 0.
+ *
+ * @param {number} ms
+ * @param {number} nowMs
+ * @returns {number|null}
+ */
+function futureSafeAgeHours(ms, nowMs) {
+  if (ms > nowMs + FUTURE_HEARTBEAT_TOLERANCE_MS) return null;
+  return Math.max(0, nowMs - ms) / (3600 * 1000);
 }
 
 /**
@@ -223,12 +244,15 @@ function currentSessionPathFor(repoRoot) {
 function currentSessionAgeHours(parsed, filePath, nowMs, fsDep) {
   const ts = typeof parsed?.timestamp === 'string' ? parsed.timestamp : null;
   const ms = ts ? Date.parse(ts) : NaN;
-  if (!Number.isNaN(ms)) {
-    return (nowMs - ms) / (3600 * 1000);
-  }
+  // #1505.2: a `timestamp` beyond the future tolerance measures nothing — it
+  // fell through as a negative age, always under the TTL, and kept the file
+  // 'fresh' forever. It is treated like an absent one: the mtime decides.
+  const fromTimestamp = Number.isNaN(ms) ? null : futureSafeAgeHours(ms, nowMs);
+  if (fromTimestamp !== null) return fromTimestamp;
   try {
     const info = fsDep.statSync(filePath);
-    return (nowMs - info.mtimeMs) / (3600 * 1000);
+    // A future mtime too → null → 'fresh': kept until the clock passes it.
+    return futureSafeAgeHours(info.mtimeMs, nowMs);
   } catch {
     return null;
   }

package/scripts/lib/maintenance-due-banner.mjs

@@ -132,6 +132,14 @@ const MS_PER_DAY = 86_400_000;
 /** The event name whose ABSENCE is the `evolve` signal. */
 const EVOLVE_EVENT = 'orchestrator.evolve.completed';
 
+/**
+ * Events-ledger window for the #1401 census (`events-retention-banner.mjs`):
+ * `null` — the one ledger question here ("was {@link EVOLVE_EVENT} EVER
+ * recorded?") is about every line ever written, so no day count bounds it; a
+ * pruned history turns the answer `undeterminable`, never "never" (#1489).
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = null;
+
 /** Pending-proposal sidecars, repo-relative (owned by auto-dream / auto-dialectic). */
 const PENDING_SIDECARS = ['.orchestrator/pending-dream.md', '.orchestrator/dialectic-pending.md'];
 
@@ -187,11 +195,13 @@ export const EVOLVE_SCAN_BUDGET_MS = 1000;
  * /evolve, which is the HR-101 failure mode this module exists to avoid.
  *
  * @param {string} repoRoot
- * @returns {{ok: boolean, lastAt: string|null, truncated: boolean}} `ok: false`
- *   ⇒ a source exists but could not be read; `truncated: true` ⇒ the budget ran
- *   out before the walk finished. In BOTH cases the caller must record
- *   `undeterminable`, never clean — a walk that did not finish has not proven
- *   "never".
+ * @returns {{ok: boolean, lastAt: string|null, truncated: boolean, historyCut: boolean}}
+ *   `ok: false` ⇒ a source exists but could not be read; `truncated: true` ⇒
+ *   the budget ran out before the walk finished. In BOTH cases the caller must
+ *   record `undeterminable`, never clean — a walk that did not finish has not
+ *   proven "never". `historyCut: true` ⇒ the walk finished but the history it
+ *   read begins after an archive that is gone (#1489: pruned by
+ *   `events-rotation.max-backups`), so a miss has not proven "never" either.
  */
 function readLastEvolveRun(repoRoot) {
   const file = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
@@ -209,8 +219,10 @@ function readLastEvolveRun(repoRoot) {
       return true;
     },
   });
-  if (scan.unreadable.length > 0) return { ok: false, lastAt: null, truncated: false };
-  return { ok: true, lastAt, truncated: scan.truncated };
+  if (scan.unreadable.length > 0) {
+    return { ok: false, lastAt: null, truncated: false, historyCut: false };
+  }
+  return { ok: true, lastAt, truncated: scan.truncated, historyCut: scan.gaps.length > 0 };
 }
 
 /**
@@ -301,7 +313,10 @@ export async function computeMaintenanceDue(opts = {}) {
     if (!evolve.ok || evolve.truncated) {
       undeterminable.push('evolve');
     } else if (evolve.lastAt === null && nudge.activeLearnings >= MAINTENANCE_MIN_LEARNINGS) {
-      markDue('evolve', `never, ${nudge.activeLearnings} active learnings`);
+      // #1489: judged only where it would flip the verdict, so a cut history
+      // adds no row to a repo the floor already keeps silent (HR-101).
+      if (evolve.historyCut) undeterminable.push('evolve');
+      else markDue('evolve', `never, ${nudge.activeLearnings} active learnings`);
     }
 
     // --- reconcile (S3) ----------------------------------------------------

package/scripts/lib/named-vault-resolver.mjs

@@ -555,9 +555,26 @@ export function normalizeRemote(url) {
  * - `file:` URL, or a bare/relative path (git's rule: no `://` and no `:`
  *   before the first `/`, a Windows drive letter counting as a path)
  *   → `file://<local path>`.
- * - Every other form (`https://`, `ssh://`, scp-like `git@host:path`) keeps its
- *   host/path and goes through {@link redactUrlCredentials}, so an
- *   `https://user:token@host/…` origin cannot leak its credential either.
+ * - Login rule, both remote forms: a userinfo other than the forge-shared `git`
+ *   is the operator's account (or a password-shaped `user:pass`) → `***@`, the
+ *   same marker {@link redactUrlCredentials} uses; it never takes part in the
+ *   suffix match, so dropping it costs the line no diagnostic value.
+ * - A URL form (`ssh://`, `https://`, … #1490 item 5) applies the login rule,
+ *   keeps its host/port, and keeps its path UNLESS the path has the absolute
+ *   home-dir shape (`/home/<u>…`, `/Users/<u>…`, `/root…`, `/~…`) →
+ *   `/<remote path>`. In URL form every path starts with `/`, so a forge's
+ *   `/org/repo` and a plain `/srv/vault` cannot be told from a filesystem path;
+ *   only the home-dir shape is the owner leak, and the forge shape is what the
+ *   suffix comparison is about. The result still goes through
+ *   {@link redactUrlCredentials}, so a bare `https://git@` (a token slot there)
+ *   is redacted as before. A `://` with no scheme before it (`/srv/a://b`,
+ *   `host:/p://q`) is no URL form: the path and scp rules read it (#1496).
+ * - A scp-like `[user@]host:path` (#1487 item 10) applies the login rule and
+ *   keeps the host and a RELATIVE path — the repo shape the canonical-suffix
+ *   comparison is about. Here a path starting with `/` or `~` is unambiguous: a
+ *   filesystem path on that host (typically a home dir) → `<remote path>`. A
+ *   bracketed IPv6 host (`[::1]:path`, `user@[::1]:path`, `[user@::1]:path`)
+ *   follows the same two rules.
  *
  * Returns `''` for an empty/absent origin; callers supply their own wording.
  * @param {string|undefined|null} url
@@ -567,9 +584,35 @@ export function describeOriginForLog(url) {
   const s = String(url ?? '').trim();
   if (!s) return '';
   if (/^file:/i.test(s)) return 'file://<local path>';
-  if (s.includes('://')) return redactUrlCredentials(s);
+  const login = (u) => (u === undefined ? '' : u === 'git' ? 'git@' : '***@');
+  // A `://` with no scheme in front of it is no URL — git's is_url() reads
+  // such a string by the scp/local rules below, and so does this (#1496: it
+  // used to be printed verbatim, home dir and all).
+  const m = /^([a-z][a-z0-9+.-]*:\/\/)([^/]*)(.*)$/is.exec(s);
+  if (m) {
+    const [, scheme, authority, urlPath] = m;
+    // userinfo runs to the LAST '@' of the authority (a password may hold one).
+    const at = authority.lastIndexOf('@');
+    const user = at === -1 ? undefined : authority.slice(0, at);
+    const homeShaped = /^\/(?:~|(?:home|Users)\/[^/]+(?:\/|$)|root(?:\/|$))/.test(urlPath);
+    return redactUrlCredentials(
+      `${scheme}${login(user)}${authority.slice(at + 1)}${homeShaped ? '/<remote path>' : urlPath}`,
+    );
+  }
   const scpLike = /^[^/\\]*:/.test(s) && !/^[a-z]:[\\/]/i.test(s);
-  return scpLike ? redactUrlCredentials(s) : 'file://<local path>';
+  if (!scpLike) return 'file://<local path>';
+  // Split host from path the way git's connect.c host_end() does: a host in
+  // brackets — leading, or right after `user@` — runs to its `]`, so the ':'
+  // inside an IPv6 literal (`[::1]`, `[alice@::1]`) is never the separator.
+  // Otherwise the userinfo runs to the last '@' and the host to the next ':';
+  // `scpLike` guarantees a ':' with no '/' or '\' before it, so that second
+  // pattern always matches.
+  const [, user, host, path] =
+    /^(?:([^[]*)@)?(\[[^\]]*\]):(.*)$/s.exec(s) ?? /^(?:(.*)@)?([^@:]*):(.*)$/s.exec(s);
+  // A login inside the brackets is the same account as one before them.
+  const shownHost = host.replace(/^\[([^\]]*)@/, (_, u) => `[${login(u)}`);
+  const where = /^[/~]/.test(path) ? '<remote path>' : path;
+  return redactUrlCredentials(`${login(user)}${shownHost}:${where}`);
 }
 
 /**

package/scripts/lib/orphan-reaper/no-follow-append.mjs

@@ -0,0 +1,87 @@
+/**
+ * orphan-reaper/no-follow-append.mjs — the ONE hardened JSONL append the
+ * reaper's two ledgers share: the B5 kill audit (`reaper-audit.mjs`) and the
+ * gate-process ledger (`../process-group.mjs`). It was inline in the audit
+ * writer; the gate ledger still used a plain `appendFileSync(path)` (#1489).
+ *
+ * Imports nothing but `node:fs`, so `process-group.mjs` takes it without
+ * growing its closure. The read-side twin is `readTailWindow(file, n,
+ * { noFollow: true })` in `../tail-window.mjs`.
+ */
+
+import { appendFileSync, closeSync, constants as fsConstants, fstatSync, openSync } from 'node:fs';
+
+/** The one refusal every hardened ledger writer prints — the appends here and
+ *  the atomic prune rewrites (`replaceRegularFile`) in both ledger modules. */
+export const NOT_A_REGULAR_FILE = 'not a regular file (a symlink is never written through) — left untouched';
+
+/**
+ * `open(2)` flags of the append. `O_NOFOLLOW` makes the kernel refuse a
+ * symlink as the last path component (ELOOP) in the same call that opens the
+ * file, so there is no lstat-then-open window; `O_NONBLOCK` turns a planted FIFO
+ * with no reader into ENXIO instead of blocking in `open` (a plain append open
+ * of a FIFO waits for a reader that never comes — reproduced 2026-10-02, #1487).
+ * On a regular file `O_NONBLOCK` changes nothing.
+ * Named ceiling (BV-004): both are POSIX-only — Node leaves them undefined on
+ * Windows, where a linked ledger is still followed; revisit if the reaper or the
+ * gate ledger ever runs there.
+ */
+const APPEND_FLAGS = fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT
+  | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+
+/** @returns {Error & {code: string}} */
+function notARegularFile() {
+  return Object.assign(new Error(NOT_A_REGULAR_FILE), { code: 'ERR_NOT_REGULAR_FILE' });
+}
+
+/**
+ * Append `data` to `target`, creating it if absent — but never THROUGH a link
+ * and never blocked by a FIFO.
+ *
+ * The check is the open itself ({@link APPEND_FLAGS}) plus an `fstat` of the
+ * descriptor that was opened — never a separate lstat. That `fstat` refuses
+ * what the open let through: a FIFO that HAD a reader, a directory, a device,
+ * and a HARD-linked file (`nlink !== 1`): `ln <victim> <ledger>` passes every
+ * symlink check, and each append would then land in the victim (reproduced
+ * 2026-10-02 against the audit).
+ *
+ * THROWS — mapping a failure to a WARN line is the caller's job, as with
+ * `readTailWindow`. A symlink or any non-regular file throws
+ * `code: 'ERR_NOT_REGULAR_FILE'` with message {@link NOT_A_REGULAR_FILE}; a
+ * hard-linked file throws `code: 'ERR_HARD_LINKED'`; a FIFO without a reader
+ * throws the kernel's ENXIO unchanged; every other fs error passes through.
+ *
+ * @param {string} target  Absolute path; its directory must already exist.
+ * @param {string} data
+ * @returns {void}
+ */
+export function appendNoFollow(target, data) {
+  let fd;
+  try {
+    fd = openSync(target, APPEND_FLAGS);
+  } catch (err) {
+    throw err?.code === 'ELOOP' ? notARegularFile() : err;
+  }
+  try {
+    const stats = fstatSync(fd);
+    if (!stats.isFile()) throw notARegularFile();
+    // nlink 0: the name was replaced between open and fstat (a concurrent prune
+    // renames a fresh inode over it). Not a planted link — say so, so the
+    // operator does not go hunting for one.
+    if (stats.nlink === 0) {
+      throw Object.assign(
+        new Error('replaced while being opened (a concurrent rewrite renamed a new file over it) — this record was not written'),
+        { code: 'ERR_UNLINKED' },
+      );
+    }
+    if (stats.nlink !== 1) {
+      throw Object.assign(
+        new Error(`hard-linked (${stats.nlink} names) — an append would write into every one of them; left untouched`),
+        { code: 'ERR_HARD_LINKED' },
+      );
+    }
+    appendFileSync(fd, data, 'utf8');
+  } finally {
+    try { closeSync(fd); } catch { /* nothing left to release */ }
+  }
+}