session-orchestrator 5.2.0 → 5.4.0

package/scripts/fleet-checkin.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * fleet-checkin.mjs — write this session's fleet check-in (#1462, PRD !53 § 3.2).
+ *
+ * Thin CLI over `scripts/lib/fleet-protocol.mjs`, called by session-start
+ * Phase 7.6 and the operations-contract peer preflight BEFORE the first writing
+ * action of a session.
+ *
+ * Usage:
+ *   echo '<check-in JSON>' | node scripts/fleet-checkin.mjs
+ *
+ * Reads one JSON object from stdin, stamps `zeit` (always overwritten), validates
+ * it with `validateCheckin()`, and writes it atomically (tmp file + rename in
+ * the target directory, mode 0600) to `<navigatorDir>/checkin/<session>.json`.
+ * Then reads the navigator lease and emits `orchestrator.fleet.checkin` with the
+ * payload `{ session, repo, modus, kandidaten, navigator_state }` — no paths, no
+ * quota, no `auftrag_ref`.
+ *
+ * stdout: one JSON line `{ ok, path, navigator_state, event }`.
+ *
+ * Exit codes:
+ *   0 — check-in written (an event failure only WARNs; `event: false` on stdout)
+ *   1 — write error
+ *   2 — invalid input (not JSON, not an object, or validation errors; no file)
+ */
+
+import { randomBytes } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { emitEvent } from './lib/events.mjs';
+import {
+  checkinPath,
+  navigatorDir,
+  readNavigatorLease,
+  utcSecondsTimestamp,
+  validateCheckin,
+} from './lib/fleet-protocol.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const PREFIX = 'fleet-checkin:';
+
+/** @returns {Promise<string>} */
+async function readStdin() {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+/**
+ * Create `<navigatorDir>/checkin/` (0700) and write `record` atomically to
+ * `target` (0600). Refuses a `checkin/` that is not a real directory, so a
+ * planted symlink cannot redirect the chmod or the write.
+ * @param {string} target
+ * @param {object} record
+ */
+async function writeCheckinFile(target, record) {
+  const checkinDir = path.dirname(target);
+  await fs.mkdir(navigatorDir(), { recursive: true, mode: 0o700 });
+  await fs.mkdir(checkinDir, { recursive: true, mode: 0o700 });
+  const st = await fs.lstat(checkinDir);
+  if (!st.isDirectory()) throw new Error(`${checkinDir} is not a directory`);
+  // mkdir's mode does not apply to a directory that already existed.
+  await fs.chmod(checkinDir, 0o700);
+
+  const tmp = path.join(checkinDir, `.${path.basename(target)}.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    // `wx`: never follow or reuse a pre-existing path at the tmp name.
+    await fs.writeFile(tmp, JSON.stringify(record, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+    // The creation mode is filtered through the umask; pin it explicitly.
+    await fs.chmod(tmp, 0o600);
+    await fs.rename(tmp, target);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+/** @returns {Promise<number>} exit code */
+async function main() {
+  let input;
+  try {
+    input = JSON.parse(await readStdin());
+  } catch {
+    process.stderr.write(`${PREFIX} stdin is not valid JSON\n`);
+    return 2;
+  }
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    process.stderr.write(`${PREFIX} stdin must be a JSON object\n`);
+    return 2;
+  }
+
+  const record = { ...input, zeit: utcSecondsTimestamp() };
+  const errors = validateCheckin(record);
+  if (errors.length > 0) {
+    for (const e of errors) process.stderr.write(`${PREFIX} ${e}\n`);
+    return 2;
+  }
+
+  const target = checkinPath(record.session);
+  try {
+    await writeCheckinFile(target, record);
+  } catch (err) {
+    process.stderr.write(`${PREFIX} write failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+
+  const { state: navigatorState } = await readNavigatorLease();
+
+  let event = true;
+  try {
+    const repoRoot = (process.env.CLAUDE_PROJECT_DIR || '').trim() || process.cwd();
+    await emitEvent(
+      'orchestrator.fleet.checkin',
+      {
+        session: record.session,
+        repo: record.repo,
+        modus: record.modus,
+        kandidaten: record.kandidaten,
+        navigator_state: navigatorState,
+      },
+      { repoRoot },
+    );
+  } catch (err) {
+    event = false;
+    process.stderr.write(
+      `${PREFIX} WARN: check-in written but event emission failed: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+
+  // Report the path with `~` for the home prefix: stdout lands in transcripts.
+  const home = os.homedir();
+  const shownPath = target.startsWith(`${home}${path.sep}`) ? `~${target.slice(home.length)}` : target;
+  process.stdout.write(JSON.stringify({ ok: true, path: shownPath, navigator_state: navigatorState, event }) + '\n');
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  main().then(
+    (code) => { process.exitCode = code; },
+    (err) => {
+      process.stderr.write(`${PREFIX} ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exitCode = 1;
+    },
+  );
+}

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-frontmatter.mjs

@@ -21,11 +21,11 @@ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 
 // Aliases per https://code.claude.com/docs/en/sub-agents § model resolution.
 // Full model IDs (claude-{opus|sonnet|haiku|fable}-N[-N][-YYYYMMDD], e.g.
-// "claude-opus-4-7", "claude-sonnet-5", "claude-fable-5-20260101") also
+// "claude-opus-5-5", "claude-sonnet-5", "claude-fable-5-20260101") also
 // accepted via MODEL_ID_RE. `fable` is a valid upstream model family
 // alongside opus/sonnet/haiku (#768) — the trailing numeric group is
 // optional so both the two-part ("claude-sonnet-5") and three-part
-// ("claude-opus-4-7") ID shapes validate.
+// ("claude-opus-5-5") ID shapes validate.
 // Exported so persona-panel modules (catalog-loader.mjs, persona-gate-wave.mjs) can
 // validate against the SSOT instead of re-declaring (W4 architect MED-1, 2026-05-19).
 export const ALLOWED_MODEL_ALIASES = new Set(['inherit', 'sonnet', 'opus', 'haiku', 'fable']);
@@ -187,7 +187,7 @@ export function validateAgentFrontmatter(frontmatter) {
     errors.push({
       path: 'model',
       rule: 'enum',
-      message: `model must be one of ${[...ALLOWED_MODEL_ALIASES].map((m) => JSON.stringify(m)).join('|')} or a full model ID like "claude-opus-4-7" or "claude-sonnet-5" (got ${JSON.stringify(model)})`,
+      message: `model must be one of ${[...ALLOWED_MODEL_ALIASES].map((m) => JSON.stringify(m)).join('|')} or a full model ID like "claude-opus-5-5" or "claude-sonnet-5" (got ${JSON.stringify(model)})`,
     });
   }
 

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