session-orchestrator 5.2.0 → 5.3.0

package/scripts/eval-session.mjs

@@ -8,7 +8,8 @@
  * Follows .claude/rules/cli-design.md:
  *   - `--json` for machine output; human-readable by default.
  *   - Data → stdout, diagnostics → stderr.
- *   - Exit codes: 0 success/match · 1 user-error/drift · 2 system error.
+ *   - Exit codes: 0 success/match · 1 user-error/drift · 2 system error ·
+ *     3 verify version-mismatch (non-standard, documented in --help).
  *
  * ## Append failures are NOT exit 0 (GitLab #969)
  *
@@ -40,6 +41,17 @@
  * Session-end Phase 3.7d remains advisory and MUST NOT gate on this exit code —
  * it catches a non-zero exit and logs a WARN (skills/session-end/SKILL.md).
  *
+ * ## A rubric change is not scoring drift (GitLab #1400)
+ *
+ * `--verify` re-scores a stored record with the CURRENT engine. When the stored
+ * `rubric_version` differs from `RUBRIC_VERSION`, the two sides answer different
+ * pre-registered check sets, so neither MATCH nor DRIFT is true: the run exits
+ * `3` with `verdict: "version-mismatch"` and re-scores nothing. Exit `0` would
+ * sell a cross-rubric comparison as a reproducibility proof; exit `1` would put
+ * a planned rubric bump in the same bucket as a forged record. Measured
+ * 2026-09-19: all 40 records in this repo's journal are `rubric-v1` and every
+ * one of them exited 1 as DRIFT under the rubric-v2 engine.
+ *
  * Usage:
  *   eval-session.mjs [--session <id>] [--json] [--no-write]
  *                    [--metrics-dir <path>] [--rubric <path>]
@@ -68,6 +80,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const EXIT_OK = 0;
 const EXIT_USER = 1;
 const EXIT_SYSTEM = 2;
+/** Non-standard, `--verify` only: the stored record predates the current rubric (#1400). */
+const EXIT_VERSION_MISMATCH = 3;
 
 function readPkgVersion() {
   try {
@@ -103,6 +117,9 @@ EXIT CODES
   1  user error (session not found, unknown run-id, record failed validation)
      / verify drift
   2  system error (could not append the record to the eval journal)
+  3  verify version-mismatch: the stored record was scored under a different
+     rubric than ${RUBRIC_VERSION}, so it is not re-verifiable with this engine
+     (non-standard code — neither a match nor drift)
 `;
 
 function fail(exitCode, message) {
@@ -211,6 +228,49 @@ function runVerify(runId, values) {
     fail(EXIT_USER, `--verify: run-id not found in eval journal: ${runId}`);
   }
 
+  // #1400 — check the rubric BEFORE re-scoring. A record scored under another
+  // rubric answers a different pre-registered check set, so re-running the
+  // current engine over it produces a comparison nobody asked for. A record
+  // with no `rubric_version` at all is unattributable and counts as a mismatch.
+  const storedRubric = typeof stored.rubric_version === 'string' && stored.rubric_version
+    ? stored.rubric_version
+    : null;
+  if (storedRubric !== RUBRIC_VERSION) {
+    // Deliberately NO diff of the dimensions the two rubrics share. Such a diff
+    // is technically possible but would carry almost no signal here. Measured
+    // 2026-09-19 over this repo's 40-record journal, replaying every record
+    // through `evaluateSession` + `diffDimensions`: all 40 differ on
+    // `process-safety` (its formula IS the v2 change) and all 40 gain a
+    // `present-in-fresh-only` `guard-friction`; restricted to the
+    // formula-unchanged dimensions, only 4 of 40 are byte-identical and the
+    // other 36 differ on `verification-evidence` / `gate-health` because the
+    // events they were scored from predate this journal's `events.jsonl`. So a
+    // "common dimensions" diff would re-report 90% of the journal as drift under
+    // a new name — the same misdirection in another shape (HR-101: a class that
+    // fires on ~90% of samples is a broken instrument, not a signal).
+    // Ceiling: holds while a rubric bump coincides with truncated evidence.
+    // Revisit-Trigger: the next rubric bump where every stored record's source
+    // events are still present — then a common-dimension diff carries signal.
+    if (values.json) {
+      writeStdoutLineSync(
+        JSON.stringify({
+          run_id: runId,
+          match: false,
+          verdict: 'version-mismatch',
+          stored_rubric_version: storedRubric,
+          engine_rubric_version: RUBRIC_VERSION,
+        }),
+      );
+    } else {
+      writeStdoutLineSync(
+        `VERSION-MISMATCH: ${runId} was scored under ${storedRubric ?? '(no rubric_version)'}; ` +
+          `this engine scores ${RUBRIC_VERSION} — not re-verifiable with this engine ` +
+          '(not drift, not a match).',
+      );
+    }
+    process.exit(EXIT_VERSION_MISMATCH);
+  }
+
   let fresh;
   try {
     fresh = evaluateSession({
@@ -236,7 +296,9 @@ function runVerify(runId, values) {
 
   if (diffs.length === 0) {
     if (values.json) {
-      writeStdoutLineSync(JSON.stringify({ run_id: runId, match: true, dimensions: fresh.dimensions.length }));
+      writeStdoutLineSync(
+        JSON.stringify({ run_id: runId, match: true, verdict: 'match', dimensions: fresh.dimensions.length }),
+      );
     } else {
       writeStdoutLineSync(`MATCH: ${runId} re-evaluates identically across ${fresh.dimensions.length} dimension(s).`);
     }
@@ -244,7 +306,7 @@ function runVerify(runId, values) {
   }
 
   if (values.json) {
-    writeStdoutLineSync(JSON.stringify({ run_id: runId, match: false, diffs }));
+    writeStdoutLineSync(JSON.stringify({ run_id: runId, match: false, verdict: 'drift', diffs }));
   } else {
     const out = [`DRIFT: ${runId} re-evaluation differs from the stored record:`];
     for (const d of diffs) {

package/scripts/generate-agents-skills.mjs

@@ -12,10 +12,11 @@
  * This generator writes two artefacts, both DERIVED and never hand-edited:
  *
  *   1. `AGENTS.md`               — a BYTE-IDENTICAL copy of `CLAUDE.md`.
- *   2. `.agents/skills/<name>/SKILL.md` — a portable mirror of each
- *      `skills/<name>/SKILL.md`, carrying ONLY agentskills.io-spec-legal
+ *   2. `.agents/skills/<name>/SKILL.md` — a portable mirror of each skill and
+ *      command (commands own overlapping names), carrying ONLY spec-legal
  *      frontmatter plus a pointer body (progressive disclosure — the mirror
- *      never duplicates the canonical instructions).
+ *      never duplicates the canonical instructions). Native Codex invocation
+ *      policy travels in an adjacent `agents/openai.yaml` when applicable.
  *
  * ## Why a generated copy and NOT a symlink (measured, not preferred)
  *
@@ -53,6 +54,9 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
+import { isUserInvocableValue } from './lib/user-invocable-skills.mjs';
+
+const POLICY_MARKER = '# Generated by scripts/generate-agents-skills.mjs; do not edit.\n';
 
 /**
  * The complete set of SKILL.md frontmatter keys agentskills.io permits outside
@@ -159,29 +163,40 @@ export function toPortableFrontmatter(source, skillName) {
  *
  * @param {string} skillName
  * @param {Record<string, unknown>} portableFm
+ * @param {string} [canonical] plugin-relative source path; defaults to the skill
  * @returns {string}
  */
-export function renderMirror(skillName, portableFm) {
+export function renderMirror(skillName, portableFm, canonical = `skills/${skillName}/SKILL.md`) {
   const front = yaml.dump(portableFm, { lineWidth: -1, noRefs: true, quotingType: '"' });
-  const canonical = `skills/${skillName}/SKILL.md`;
-  return [
+  const command = canonical.startsWith('commands/');
+  const lines = [
     '---',
     front.trimEnd(),
     '---',
     '',
     `# ${skillName}`,
     '',
-    `> **Portable mirror — generated, do not edit.** The canonical skill body lives at`,
+    `> **Portable mirror — generated, do not edit.** The canonical workflow lives at`,
     `> [\`${canonical}\`](../../../${canonical}); read that file for the full instructions.`,
     `> This mirror carries only agentskills.io-spec-legal frontmatter so harnesses that`,
     `> discover skills under \`.agents/skills/\` can find and route to the skill.`,
     '>',
     '> Regenerate with `node scripts/generate-agents-skills.mjs`.',
     '',
-  ].join('\n');
+    'Read the linked document in full and follow its complete workflow, including prechecks and stop conditions. Resolve its link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root and relative links in the canonical document from its own directory. Keep the user’s project as the target of project operations.',
+  ];
+  if (command || isUserInvocableValue(portableFm.metadata?.['user-invocable'])) lines.push(
+    '',
+    '`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. Pass command arguments through structured tool parameters or safely quoted individual arguments.',
+  );
+  if (command) lines.push(
+    '',
+    'Read the full command before invoking an internal skill. An instruction to invoke a skill (including `session-orchestrator:<name>` or the `Skill` tool) means read and follow the canonical `skills/<name>/SKILL.md` beneath the plugin root. Do not redispatch the public command adapter: a same-named command and internal skill are distinct documents, and redispatch would recurse.',
+  );
+  return [...lines, ''].join('\n');
 }
 
-/** Parse a SKILL.md's YAML frontmatter block; returns `{}` when absent/unparseable. */
+/** Parse a source's YAML frontmatter block; returns null when absent/unparseable. */
 function readFrontmatter(absPath) {
   const content = readFileSync(absPath, 'utf8');
   const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
@@ -205,6 +220,44 @@ export function listSourceSkills(pluginRoot) {
     .sort();
 }
 
+/** Union of canonical skills and commands, preserving command precedence. */
+function listSourceEntries(pluginRoot) {
+  const sources = new Map(listSourceSkills(pluginRoot).map((name) => [name, `skills/${name}/SKILL.md`]));
+  const commands = path.join(pluginRoot, 'commands');
+  if (existsSync(commands) && statSync(commands).isDirectory()) {
+    for (const entry of readdirSync(commands, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.md') || /^[._]/.test(entry.name)) continue;
+      sources.set(entry.name.slice(0, -3), `commands/${entry.name}`);
+    }
+  }
+  return sources;
+}
+
+/** Match Codex policy precedence: command, native skill override, public skill. */
+function invocationPolicy(pluginRoot, name, canonical, fm) {
+  if (!canonical.startsWith('commands/')) {
+    const nativePath = path.join(pluginRoot, 'skills', name, 'agents', 'openai.yaml');
+    if (existsSync(nativePath)) {
+      const native = yaml.load(readFileSync(nativePath, 'utf8'), { schema: yaml.CORE_SCHEMA });
+      const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+      if (!isRecord(native) || (Object.hasOwn(native, 'policy') && !isRecord(native.policy))) {
+        throw new Error(`${nativePath}: native skill metadata and policy must be mappings`);
+      }
+      if (native.policy && Object.hasOwn(native.policy, 'allow_implicit_invocation')) {
+        if (typeof native.policy.allow_implicit_invocation !== 'boolean') {
+          throw new Error(`${nativePath}: policy.allow_implicit_invocation must be a boolean`);
+        }
+        return native.policy.allow_implicit_invocation;
+      }
+    }
+    if (!isUserInvocableValue(fm['user-invocable'], canonical)) return undefined;
+  }
+  if (Object.hasOwn(fm, 'disable-model-invocation') && typeof fm['disable-model-invocation'] !== 'boolean') {
+    throw new Error(`${canonical}: disable-model-invocation must be a boolean`);
+  }
+  return fm['disable-model-invocation'] !== true;
+}
+
 /**
  * Is `AGENTS.md` already an alias of `CLAUDE.md` by construction?
  *
@@ -268,34 +321,53 @@ export function generateAgentsSurface({ pluginRoot, check = false }) {
 
   // --- Artefact 2: .agents/skills/<name>/SKILL.md ---------------------------
   const mirrorRoot = path.join(pluginRoot, '.agents', 'skills');
-  const skills = listSourceSkills(pluginRoot);
+  const sources = listSourceEntries(pluginRoot);
+  const skills = [...sources.keys()].sort();
   let files = 0;
   let bytes = 0;
 
   for (const name of skills) {
-    const src = path.join(pluginRoot, 'skills', name, 'SKILL.md');
+    const canonical = sources.get(name);
+    const src = path.join(pluginRoot, canonical);
     const fm = readFrontmatter(src);
     if (fm === null) {
-      warnings.push(`${name}: SKILL.md has no parseable frontmatter — skipped`);
+      warnings.push(`${canonical}: has no parseable frontmatter — skipped`);
       continue;
     }
     const { fm: portable, warnings: w } = toPortableFrontmatter(fm, name);
     warnings.push(...w);
-    const rendered = renderMirror(name, portable);
-    const dest = path.join(mirrorRoot, name, 'SKILL.md');
-    files += 1;
-    bytes += Buffer.byteLength(rendered, 'utf8');
-
-    const current = existsSync(dest) ? readFileSync(dest, 'utf8') : null;
-    if (current === rendered) continue;
-    if (check) {
-      drift.push(current === null
-        ? `.agents/skills/${name}/SKILL.md is missing`
-        : `.agents/skills/${name}/SKILL.md is stale`);
-    } else {
-      mkdirSync(path.dirname(dest), { recursive: true });
-      writeFileSync(dest, rendered, 'utf8');
-      written.push(`.agents/skills/${name}/SKILL.md`);
+    const artifacts = new Map([['SKILL.md', renderMirror(name, portable, canonical)]]);
+    const policy = invocationPolicy(pluginRoot, name, canonical, fm);
+    const policyPath = path.join(mirrorRoot, name, 'agents', 'openai.yaml');
+    if (policy !== undefined) {
+      artifacts.set('agents/openai.yaml', POLICY_MARKER + yaml.dump({
+        interface: { display_name: name },
+        policy: { allow_implicit_invocation: policy },
+      }, { lineWidth: -1, noRefs: true }));
+    } else if (existsSync(policyPath) && readFileSync(policyPath, 'utf8').startsWith(POLICY_MARKER)) {
+      if (check) drift.push(`.agents/skills/${name}/agents/openai.yaml is obsolete`);
+      else {
+        rmSync(policyPath);
+        written.push(`removed .agents/skills/${name}/agents/openai.yaml`);
+      }
+    }
+    for (const [file, rendered] of artifacts) {
+      const relative = `.agents/skills/${name}/${file}`;
+      const dest = path.join(mirrorRoot, name, file);
+      files += 1;
+      bytes += Buffer.byteLength(rendered, 'utf8');
+      const current = existsSync(dest) ? readFileSync(dest, 'utf8') : null;
+      if (file === 'agents/openai.yaml' && current !== null && !current.startsWith(POLICY_MARKER)) {
+        drift.push(`${relative} conflicts with an unrelated native policy — retained`);
+        continue;
+      }
+      if (current === rendered) continue;
+      if (check) drift.push(`${relative} is ${current === null ? 'missing' : 'stale'}`);
+      else {
+        mkdirSync(path.dirname(dest), { recursive: true });
+        writeFileSync(dest, rendered, 'utf8');
+        written.push(relative);
+      }
     }
   }
 
@@ -306,7 +378,7 @@ export function generateAgentsSurface({ pluginRoot, check = false }) {
     for (const entry of readdirSync(mirrorRoot, { withFileTypes: true })) {
       if (!entry.isDirectory() || known.has(entry.name)) continue;
       if (check) {
-        drift.push(`.agents/skills/${entry.name}/ is an orphan (no skills/${entry.name}/SKILL.md)`);
+        drift.push(`.agents/skills/${entry.name}/ is an orphan (no skill or command source)`);
       } else {
         rmSync(path.join(mirrorRoot, entry.name), { recursive: true, force: true });
         written.push(`removed .agents/skills/${entry.name}/`);
@@ -356,8 +428,9 @@ function main(argv) {
     }
   } else {
     for (const w of result.warnings) process.stderr.write(`  WARN: agents-surface: ${w}\n`);
+    for (const d of result.drift) process.stderr.write(`✗ agents-surface: ${d}\n`);
     process.stdout.write(
-      `agents-surface: ${result.written.length} file(s) written, ${result.files} skill mirror(s), ${result.bytes} bytes\n`,
+      `agents-surface: ${result.written.length} file(s) written, ${result.files} portable artefact(s), ${result.bytes} bytes\n`,
     );
   }
   return result.ok ? 0 : 1;

package/scripts/generate-cursor-adapter.mjs

@@ -39,6 +39,9 @@ const CURSOR_SKILLS_DIR = path.join(ROOT, '.cursor', 'skills');
 const CHECK_ONLY = process.argv.includes('--check');
 const DESCRIPTION_MAX = 1024;
 
+/** Memo for {@link skillFlags} — skill name → parsed frontmatter + both markers. */
+const SKILL_FLAGS = new Map();
+
 function isDir(p) {
   try { return statSync(p).isDirectory(); } catch { return false; }
 }
@@ -201,11 +204,41 @@ Cursor has no Skill tool. When the command says to invoke a skill, Read \`skills
  * @returns {string[]} skill names, sorted
  */
 function userInvocableSkills() {
-  return skillDirs().filter((name) => {
-    const file = path.join(SKILLS_DIR, name, 'SKILL.md');
-    const fields = parseFrontmatter(readFileSync(file, 'utf8'));
-    return isUserInvocableValue(fields['user-invocable'], file);
-  });
+  return skillDirs().filter((name) => skillFlags(name).userInvocable);
+}
+
+/**
+ * Both boolean markers of ONE skill, parsed and judged exactly once.
+ *
+ * Memoised because the predicate is not side-effect free: a truthy-lookalike
+ * value (`yes`, `on`, `1`) emits a stderr WARN, so reading the same key from
+ * three call sites emitted the same warning three times — measured 2026-09-18
+ * on a two-skill fixture: 3 WARN lines for 2 defects. One skill, one reading,
+ * one diagnostic.
+ *
+ * @param {string} skillName
+ * @returns {{file: string, fields: Record<string, string>, userInvocable: boolean,
+ *   sourceDisablesModel: boolean, disablesModel: boolean}}
+ */
+function skillFlags(skillName) {
+  const cached = SKILL_FLAGS.get(skillName);
+  if (cached) return cached;
+  const file = path.join(SKILLS_DIR, skillName, 'SKILL.md');
+  const fields = parseFrontmatter(readFileSync(file, 'utf8'));
+  const userInvocable = isUserInvocableValue(fields['user-invocable'], file, 'user-invocable');
+  const sourceDisablesModel = isUserInvocableValue(
+    fields['disable-model-invocation'], file, 'disable-model-invocation',
+  );
+  const flags = {
+    file,
+    fields,
+    userInvocable,
+    sourceDisablesModel,
+    // See {@link disablesModelInvocation} for the two OR-ed grounds.
+    disablesModel: sourceDisablesModel || !userInvocable,
+  };
+  SKILL_FLAGS.set(skillName, flags);
+  return flags;
 }
 
 /**
@@ -217,8 +250,7 @@ function userInvocableSkills() {
  * @returns {string}
  */
 function renderSkillCommand(skillName) {
-  const skillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');
-  const fields = parseFrontmatter(readFileSync(skillPath, 'utf8'));
+  const { fields, sourceDisablesModel } = skillFlags(skillName);
   const description = clampDescription(fields.description || `Session Orchestrator skill: ${skillName}`);
   // Same GH#54 rule as renderCommand: `argument-hint` ALWAYS goes through
   // yamlQuote(), because its canonical authored form (`[mode] [--flag]`) is a
@@ -233,7 +265,7 @@ function renderSkillCommand(skillName) {
     '---',
     frontmatterLine('description', yamlQuote(description)),
     frontmatterLine('argument-hint', yamlQuote(fields['argument-hint'])),
-    isUserInvocableValue(fields['disable-model-invocation'], skillPath) ? 'disable-model-invocation: true' : null,
+    sourceDisablesModel ? 'disable-model-invocation: true' : null,
     '---',
   ].filter(Boolean).join('\n');
 
@@ -269,6 +301,18 @@ Cursor has no Skill tool. When the skill says to invoke another skill, Read \`sk
  *      (measured 2026-09-17) on no Cursor-side evidence, which is the one
  *      direction a guard fix must never move.
  *
+ * NAMED CEILING on ground 2 (BV-004). Whether Cursor reads
+ * `disable-model-invocation` at all is UNVERIFIED as of 2026-09-18: the key is
+ * documented here for Claude Code and Codex only, and `rg
+ * "disable-model-invocation" docs .claude .cursor/rules` returns zero Cursor
+ * citations. Ground 2 therefore stamps 24 wrappers on the ASSUMPTION that
+ * Cursor honours it — kept because stamping a restriction a reader ignores
+ * costs nothing, while dropping it would loosen 24 wrappers if the reader does
+ * honour it. REVISIT TRIGGER: Cursor documents the key (or a measured Cursor
+ * run shows it ignored) — then decide ground 2 on that evidence instead.
+ * Pinned by `tests/scripts/generate-cursor-adapter.test.mjs` ("stamps
+ * disable-model-invocation on ground 2 alone").
+ *
  * Truth table — both readings normalised by `isUserInvocableValue`, so every
  * form a YAML parser reads as `true` (`True`, `"true"`, `true # note`) counts
  * as `true` on BOTH axes. Ground 2 made that load-bearing rather than cosmetic:
@@ -283,18 +327,19 @@ Cursor has no Skill tool. When the skill says to invoke another skill, Read \`sk
  *   | false/absent| true           | no      |
  *   | false/absent| false/absent   | yes (2) |
  *
- * @param {Record<string, string>} fields source skill frontmatter
- * @param {string} [file] SKILL.md path, named in a demotion WARN
+ * Both readings come from {@link skillFlags} (`sourceDisablesModel ||
+ * !userInvocable`), which parses each SKILL.md once — so a truthy-lookalike
+ * value warns once per key per skill instead of once per call site.
+ *
+ * @param {string} skillName
  * @returns {boolean}
  */
-function disablesModelInvocation(fields, file) {
-  return isUserInvocableValue(fields['disable-model-invocation'], file)
-    || !isUserInvocableValue(fields['user-invocable'], file);
+function disablesModelInvocation(skillName) {
+  return skillFlags(skillName).disablesModel;
 }
 
 function renderSkill(skillName) {
-  const skillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');
-  const fields = parseFrontmatter(readFileSync(skillPath, 'utf8'));
+  const { fields } = skillFlags(skillName);
   const description = clampDescription(fields.description || `Session Orchestrator skill: ${skillName}`);
   // Same rule as renderCommand: no frontmatter value is emitted raw. `name` is
   // a directory basename today, so it is plain-safe in practice — routing it
@@ -304,7 +349,7 @@ function renderSkill(skillName) {
     `name: ${yamlQuote(skillName)}`,
     `description: ${yamlQuote(description)}`,
   ];
-  if (disablesModelInvocation(fields, skillPath)) {
+  if (disablesModelInvocation(skillName)) {
     lines.push('disable-model-invocation: true');
   }
   lines.push('---');

package/scripts/lib/agent-status.mjs

@@ -58,6 +58,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { appendJsonl } from './common.mjs';
 import { writeJsonAtomicSync } from './io.mjs';
 import { tryAcquireFileLock, releaseFileLock } from './file-lock.mjs';
+import { readTailWindow } from './tail-window.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -303,36 +304,6 @@ function newestTsMs(entries) {
   return newest;
 }
 
-/**
- * Read the last `maxBytes` of a file. Returns the raw text plus whether the
- * window cut into the file (i.e. the first line in `text` may be partial).
- * @param {string} file
- * @param {number} maxBytes
- * @returns {{ text: string, size: number, cut: boolean }}
- */
-function readTail(file, maxBytes) {
-  const fd = fs.openSync(file, 'r');
-  try {
-    const size = fs.fstatSync(fd).size;
-    const want = Math.min(size, maxBytes);
-    const start = size - want;
-    const buf = Buffer.allocUnsafe(want);
-    let read = 0;
-    while (read < want) {
-      const n = fs.readSync(fd, buf, read, want - read, start + read);
-      if (n <= 0) break;
-      read += n;
-    }
-    return { text: buf.subarray(0, read).toString('utf8'), size, cut: start > 0 };
-  } finally {
-    try {
-      fs.closeSync(fd);
-    } catch {
-      /* best-effort */
-    }
-  }
-}
-
 /**
  * Shared write path for both setters: append the JSONL record, then perform a
  * lock-serialised read-modify-write of the LWW map. No-throw.
@@ -481,7 +452,7 @@ export function rebuildCurrentFromLedger(opts = {}) {
 
   let tail;
   try {
-    tail = readTail(jsonlFile, maxBytes);
+    tail = readTailWindow(jsonlFile, maxBytes);
   } catch (err) {
     const reason = err?.code === 'ENOENT' ? 'ledger-missing' : 'ledger-unreadable';
     return {

package/scripts/lib/auq/clarity.mjs

@@ -801,9 +801,17 @@ function checkK5(q, at) {
         severity: 'fail',
         target: 'header',
         ...at,
+        // Der Text sagte bis hierher "Das Tool zeigt nur 12 — den Rest sieht der
+        // Operator nie". Das ist widerlegt: die 12 steht allein in der Prosa des
+        // Schemas (kein `.max(12)`, kein kuerzender Render-Pfad in Bundle
+        // 2.1.268), und 125 laengere Kopfzeilen wurden angenommen und beantwortet
+        // (ask-via-tool.md AUQ-006). H1 blockt deshalb nicht (BLOCKING_HURDLES =
+        // ['H2']) — die Meldung ist ein Hinweis, keine Abweisung, und darf keine
+        // Kuerzung begruenden, die es nicht braucht.
         message:
-          `Die Kopfzeile "${header}" hat ${literal} Zeichen. Das Tool zeigt nur ` +
-          `${THRESHOLDS.K5.headerCharsFail} — den Rest sieht der Operator nie.`,
+          `Die Kopfzeile "${header}" hat ${literal} Zeichen; Ziel sind ` +
+          `${THRESHOLDS.K5.headerCharsFail} Codepoints. Das Tool schneidet nicht ab — ` +
+          `Kuerzen ist optional.`,
         measured: literal,
         threshold: THRESHOLDS.K5.headerCharsFail,
         hurdle: HURDLES.H1.id,

package/scripts/lib/auq/parse.mjs

@@ -83,6 +83,7 @@ import {
   isRecommendedOption,
 } from './schema.mjs';
 import { scanFenceBlocks } from '../validate/markdown-fences.mjs';
+import { maskSource } from '../js-mask.mjs';
 
 // ---------------------------------------------------------------------------
 // Korpus-Abgrenzung
@@ -142,42 +143,22 @@ export function corpusKindOf(file) {
  * Anführungspaar, das jeder „nimm das letzte Literal der Zeile"-Ansatz als
  * Label extrahiert.
  *
+ * Seit #1388 delegiert das an den geteilten Lexer `maskSource`
+ * (`../js-mask.mjs`, Modus `keepLiterals`): gleiche Zusicherung (Länge und
+ * Zeilenumbrüche erhalten, Literal-Inhalte unangetastet), aber MIT
+ * Regex-Literal-Zweig. Die frühere handgeschriebene Fassung hatte keinen —
+ * gemessen 2026-09-18 verschluckte `const re = /\/*$/;` als vermeintlicher
+ * Block-Kommentar-Anfang alles bis zum nächsten `*` + `/`, sodass ein
+ * darunter stehendes `label: "X (Recommended)"` spurlos verschwand: ein
+ * STILLER FALSCH-NEGATIVER Befund in der Klarheitsmessung, längentreu und
+ * daher an keiner Zeilennummer erkennbar.
+ *
  * @param {string} text
  * @returns {string} gleiche Länge, Kommentarinhalt durch Leerzeichen ersetzt
  */
 export function stripComments(text) {
   if (typeof text !== 'string' || text === '') return '';
-  const out = [...text];
-  let i = 0;
-  while (i < out.length) {
-    const c = text[i];
-    if (c === '"' || c === "'" || c === '`') {
-      const lit = readStringLiteral(text, i);
-      i = lit ? lit.end : i + 1;
-      continue;
-    }
-    if (c === '/' && text[i + 1] === '/') {
-      while (i < out.length && text[i] !== '\n') out[i++] = ' ';
-      continue;
-    }
-    if (c === '/' && text[i + 1] === '*') {
-      out[i] = ' ';
-      out[i + 1] = ' ';
-      i += 2;
-      while (i < out.length && !(text[i] === '*' && text[i + 1] === '/')) {
-        if (text[i] !== '\n') out[i] = ' ';
-        i++;
-      }
-      if (i < out.length) {
-        out[i] = ' ';
-        out[i + 1] = ' ';
-        i += 2;
-      }
-      continue;
-    }
-    i++;
-  }
-  return out.join('');
+  return maskSource(text, { keepLiterals: true });
 }
 
 /**