session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/agent-frontmatter.mjs

@@ -58,7 +58,12 @@ export function parseAgentFrontmatter(contents) {
     };
   }
 
-  const match = FRONTMATTER_RE.exec(contents);
+  // A UTF-8 BOM before `---` makes FRONTMATTER_RE miss the block entirely, so a
+  // BOM-prefixed SKILL.md would parse as "no frontmatter" and every flag in it
+  // (`user-invocable` included) silently disappear.
+  const text = contents.charCodeAt(0) === 0xfeff ? contents.slice(1) : contents;
+
+  const match = FRONTMATTER_RE.exec(text);
   if (!match) {
     return {
       ok: false,
@@ -76,19 +81,36 @@ export function parseAgentFrontmatter(contents) {
   const frontmatter = /** @type {Record<string,string>} */ ({});
   const lines = fmText.split(/\r?\n/);
 
+  // Indented lines belong to whatever the preceding top-level key opened (a
+  // nested mapping, or a block scalar) — they are NOT top-level keys. Without
+  // this, `metadata:\n  user-invocable: true` was HOISTED to top level and read
+  // as the slash-command marker, so the counters saw a skill no generator did.
+  let inNestedBlock = false;
+
   for (const rawLine of lines) {
     const line = rawLine.replace(/\s+$/, '');
     if (line === '' || /^\s*#/.test(line)) continue;
 
+    if (/^\s/.test(rawLine)) {
+      if (inNestedBlock) continue;
+    } else {
+      inNestedBlock = false;
+    }
+
     // Detect block-scalar indicators on a key line, e.g. `description: >` or `description: |`
     // These are valid YAML but break Claude Code's parser.
     const blockScalarMatch = /^(\w[\w-]*):\s*[>|]\s*$/.exec(line);
     if (blockScalarMatch) {
       // Store a sentinel so the validator can emit the correct rule.
       frontmatter[blockScalarMatch[1]] = '__BLOCK_SCALAR__';
+      inNestedBlock = true;
       continue;
     }
 
+    // A bare `key:` at top level opens a nested mapping (or an empty value);
+    // everything indented under it is that mapping's business, not ours.
+    if (/^\w[\w-]*:$/.test(line)) inNestedBlock = true;
+
     const idx = line.indexOf(':');
     if (idx === -1) continue;
     const key = line.slice(0, idx).trim();

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 });
 }
 
 /**

package/scripts/lib/auq/schema.mjs

@@ -233,50 +233,16 @@ export const CRITERION_IDS = Object.freeze(Object.keys(CRITERIA));
  */
 export const TOTAL_WEIGHT = CRITERION_IDS.reduce((sum, id) => sum + CRITERIA[id].weight, 0);
 
-// ---------------------------------------------------------------------------
-// Die zwei harten Hürden
-// ---------------------------------------------------------------------------
-
-/**
- * Hürden sind KEINE gewichteten Kriterien. Eine gerissene Hürde ergibt Note F,
- * unabhängig von der Punktzahl — deshalb stehen sie getrennt und werden in
- * `AuqScore.hurdlesBroken` geführt, nicht in `points` verrechnet.
- *
- * @type {Readonly<Record<'H1'|'H2', Readonly<{id:string,title:string,rule:string,criterion:string,evidence:string}>>>}
- */
-export const HURDLES = Object.freeze({
-  H1: Object.freeze({
-    id: 'H1',
-    title: 'Kopfzeile höchstens 12 Zeichen',
-    rule: 'codepointLength(header) <= 12',
-    criterion: 'K5',
-    evidence:
-      'Gemessen 2026-08-22: 26 von 42 Kopfzeilen-Literalen reißen diese Grenze (62 %), ' +
-      'Spitzenwert 54 Zeichen. Die 12 ist die Stilangabe der Tool-Beschreibung ' +
-      '(`max 12 chars`), KEINE erzwungene Grenze: im Bundle 2.1.268 steht die Zahl nur ' +
-      'in ebendieser Beschreibung, es gibt kein `.max(12)` im Zod-Schema und keinen ' +
-      'Render-Pfad, der sie liest — 125 längere Kopfzeilen wurden vom Tool angenommen ' +
-      'und beantwortet (gemessen 2026-09-11). Deshalb gilt H1 nur für VORLAGEN, wo ein ' +
-      'Autor kostenlos kürzen kann; zur Laufzeit meldet der Hook sie und blockt nicht ' +
-      '(siehe BLOCKING_HURDLES in hooks/pre-auq-clarity.mjs).',
-  }),
-  H2: Object.freeze({
-    id: 'H2',
-    title: '2–4 Optionen je Frage, genau eine Empfehlung auf Platz 1',
-    rule: 'options.length zwischen 2 und 4 JE FRAGE, und isRecommended nur bei index 0',
-    criterion: 'K6',
-    evidence:
-      'Pro Block gezählt meldet skills/plan/SKILL.md:137 fälschlich 14 Optionen — ' +
-      'es ist ein legaler Vierfragen-Block. Der Zähler zählt je Frage.',
-  }),
-});
-
-/** Stabile Reihenfolge. */
-export const HURDLE_IDS = Object.freeze(Object.keys(HURDLES));
-
 // ---------------------------------------------------------------------------
 // Schwellen — die einzige Stelle, an der eine Zahl steht
 // ---------------------------------------------------------------------------
+//
+// DEFINITIONSREIHENFOLGE IST TRAGEND: `HURDLES` weiter unten baut seine
+// operator-sichtbaren Sätze per Template-Literal aus `THRESHOLDS`, und ein
+// Template-Literal wird beim Laden des Moduls ausgewertet. Steht `THRESHOLDS`
+// wieder unter `HURDLES`, wirft der Import mit `ReferenceError` — auf einem
+// Modul, das `hooks/pre-auq-clarity.mjs` in JEDER Session lädt, ist das eine
+// host-weite Sperre, kein Testfehler.
 
 /**
  * Alle Schwellen, nach Kriterium gruppiert. clarity.mjs liest ausschließlich
@@ -356,6 +322,55 @@ export const THRESHOLDS = Object.freeze({
   }),
 });
 
+// ---------------------------------------------------------------------------
+// Die zwei harten Hürden
+// ---------------------------------------------------------------------------
+
+/**
+ * Hürden sind KEINE gewichteten Kriterien. Eine gerissene Hürde ergibt Note F,
+ * unabhängig von der Punktzahl — deshalb stehen sie getrennt und werden in
+ * `AuqScore.hurdlesBroken` geführt, nicht in `points` verrechnet.
+ *
+ * `title` und `rule` werden dem Operator GEDRUCKT (check-auq-clarity.mjs,
+ * auq-audit.mjs, der Deny-Text von hooks/pre-auq-clarity.mjs). Deshalb steht
+ * keine Zahl darin, sondern die Schwelle selbst: eine verschobene Schwelle mit
+ * einem stehengebliebenen Satz daneben ist eine Zeile, die den Operator belügt.
+ *
+ * @type {Readonly<Record<'H1'|'H2', Readonly<{id:string,title:string,rule:string,criterion:string,evidence:string}>>>}
+ */
+export const HURDLES = Object.freeze({
+  H1: Object.freeze({
+    id: 'H1',
+    title: `Kopfzeile höchstens ${THRESHOLDS.K5.headerCharsFail} Zeichen`,
+    rule: `codepointLength(header) <= ${THRESHOLDS.K5.headerCharsFail}`,
+    criterion: 'K5',
+    // `evidence` zitiert die Tool-Beschreibung des Bundles wörtlich
+    // (`max 12 chars`, `.max(12)`). Diese 12 ist die Zahl DES BUNDLES, nicht
+    // unsere Schwelle — sie bleibt ein Literal, auch wenn K5 sich bewegt.
+    evidence:
+      'Gemessen 2026-08-22: 26 von 42 Kopfzeilen-Literalen reißen diese Grenze (62 %), ' +
+      'Spitzenwert 54 Zeichen. Die 12 ist die Stilangabe der Tool-Beschreibung ' +
+      '(`max 12 chars`), KEINE erzwungene Grenze: im Bundle 2.1.268 steht die Zahl nur ' +
+      'in ebendieser Beschreibung, es gibt kein `.max(12)` im Zod-Schema und keinen ' +
+      'Render-Pfad, der sie liest — 125 längere Kopfzeilen wurden vom Tool angenommen ' +
+      'und beantwortet (gemessen 2026-09-11). Deshalb gilt H1 nur für VORLAGEN, wo ein ' +
+      'Autor kostenlos kürzen kann; zur Laufzeit meldet der Hook sie und blockt nicht ' +
+      '(siehe BLOCKING_HURDLES in hooks/pre-auq-clarity.mjs).',
+  }),
+  H2: Object.freeze({
+    id: 'H2',
+    title: `${THRESHOLDS.K6.optionsMin}–${THRESHOLDS.K6.optionsMax} Optionen je Frage, genau eine Empfehlung auf Platz 1`,
+    rule: `options.length zwischen ${THRESHOLDS.K6.optionsMin} und ${THRESHOLDS.K6.optionsMax} JE FRAGE, und isRecommended nur bei index 0`,
+    criterion: 'K6',
+    evidence:
+      'Pro Block gezählt meldet skills/plan/SKILL.md:137 fälschlich 14 Optionen — ' +
+      'es ist ein legaler Vierfragen-Block. Der Zähler zählt je Frage.',
+  }),
+});
+
+/** Stabile Reihenfolge. */
+export const HURDLE_IDS = Object.freeze(Object.keys(HURDLES));
+
 /** Höchstlänge eines Zitats in einem Befund (Codepoints). */
 export const EXCERPT_MAX_CHARS = 80;