session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/reconcile/rule-expiry-sweep.mjs

@@ -37,6 +37,15 @@
  *   1. **Unresolvable id → the entry is KEPT** and counted in
  *      `unresolvedPairIds`. A sweep that guessed would delete prose on no
  *      evidence, and a file with any unresolved pair is never deleted.
+ *   1b. **Unrecognised counter sentence → `action: 'keep'` + a `skipped`
+ *      record (`no-counter-sentence`), and NO write of any kind** — not a
+ *      rewrite, not a raise, not a delete. Every write here moves the
+ *      frontmatter `expires-at` and the body sentence that restates it; when
+ *      only the header moves, the file ships a header contradicting a body
+ *      sentence that forbids exactly that correction (GH#70, reported from a
+ *      German-language consumer corpus 2026-09-20). Recognising a second
+ *      spelling ({@link COUNTER_FORMS}) is the narrow half of that fix; the
+ *      refusal is the half that holds for the third language too.
  *   2. **Ambiguous file → `action: 'keep'` + a `skipped` record.** The
  *      entry↔pair mapping is POSITIONAL: the k-th `### ` heading belongs to the
  *      k-th non-`markers only` pair. That 1:1 mapping holds in only 3 of the 7
@@ -48,28 +57,54 @@
  *      `no-1to1-mapping` and touches nothing. It never guesses which paragraph
  *      belongs to which learning.
  *
- * ## Header recompute happens ONLY on a file this sweep rewrites
+ * ## Header recompute is ONE-DIRECTIONAL: raised, never lowered
  *
  * A consolidated file's frontmatter `expires-at` plus the body sentence
  * ``**`expires-at` <D> = the EARLIEST of the <N> absorbed dates**`` must not
- * outlive its shortest-lived content. Both are recomputed — but only for a file
- * the sweep actually rewrites. A file with nothing expired is left
- * BYTE-IDENTICAL, deliberately, because a recompute-on-every-run would silently
- * shorten a healthy file's TTL on the very first live invocation. The
- * discrepancy is REPORTED instead, as the per-plan `advisory` field — see
- * {@link headerAdvisory}, which is computed BEFORE the `no-1to1-mapping` skip
- * so a skipped file still gets one.
- *
- * Measured 2026-09-17 (`node scripts/sweep-expired-rules.mjs --json`, 7 files
- * scanned, 0 expired): **6 of the 7 carry a discrepancy** — `identity-and-locks`
- * 2026-10-01 vs 2026-10-02, `measurement-discipline` 2026-10-04 vs 2026-10-02,
- * `process-contracts` 2026-10-04 vs 2026-10-27, `review-and-adapter-contracts`
- * 2026-10-04 vs 2026-10-02, `test-hygiene` 2026-10-20 vs 2026-10-07,
- * `toolchain-and-build` 2026-10-01 vs 2026-10-16; only `guard-design` agrees
- * with its content. Three of the six are the harmful direction — a header
- * OUTLIVING its content: `measurement-discipline`, `review-and-adapter-contracts`
- * and `test-hygiene`. The other three expire EARLIER than they need to, which
- * costs injection but loses nothing.
+ * outlive its shortest-lived content. The two directions of a
+ * header-vs-content discrepancy are NOT symmetric, so they are handled
+ * differently:
+ *
+ *   - **Header EARLIER than the earliest absorbed date → RAISED, and that raise
+ *     is itself a rewrite trigger** (`action: 'rewrite'`,
+ *     `reason: 'header-raise'`). Left alone, the cliff has no way back:
+ *     `scripts/lib/rule-loader.mjs` drops a file whose header has passed out of
+ *     injection even though not one absorbed entry expired, while the surviving
+ *     `learning-key`/`learning-id` markers keep `/reconcile` treating those
+ *     learnings as materialized — so the substance goes dark silently and is
+ *     never re-proposed. Measured 2026-09-18 (`--json`, live corpus): 3 of 7
+ *     files are in that state (`identity-and-locks` 2026-10-01 vs 2026-10-02,
+ *     `process-contracts` 2026-10-04 vs 2026-10-27, `toolchain-and-build`
+ *     2026-10-01 vs 2026-10-16), i.e. 31.5 kB of corpus that would fall dark
+ *     with nothing expired.
+ *   - **Header LATER than the earliest absorbed date → NEVER lowered**, only
+ *     reported via the per-plan `advisory` field. Lowering on every run would
+ *     shorten a healthy file's TTL — killing an entry early — on the very first
+ *     live invocation, which is the direction that destroys substance rather
+ *     than preserving it.
+ *
+ * The raise is MINIMAL: exactly the frontmatter `expires-at:` line and the
+ * `COUNTER_RE` body sentence change; every other byte of the file is left
+ * untouched (see {@link rewriteHeaderOnly}). It needs no entry↔pair mapping —
+ * it compares the frontmatter date against dates read out of `learnings.jsonl`
+ * by id — so a `no-1to1-mapping` file gets it too, exactly like the advisory
+ * (see {@link headerAdvisory}); that file's `skipped` record refers to the
+ * PROSE sweep, which still touches nothing there.
+ *
+ * `reason` rather than a novel `action` value, deliberately: the CLI
+ * (`scripts/sweep-expired-rules.mjs`) aggregates its human summary line and its
+ * `applied` counters over the three actions `rewrite`/`delete`/`keep` only, so a
+ * fourth action name would make a header raise invisible in exactly the preview
+ * an operator reads before `--apply`. A raise IS a write; it is counted as one.
+ *
+ * Measured 2026-09-18 (`node scripts/sweep-expired-rules.mjs --json`, 7 files
+ * scanned, 0 expired, 0 skipped): **3 of the 7 carry a discrepancy**, all three
+ * in the header-EARLIER direction and therefore all three raises —
+ * `identity-and-locks` 2026-10-01 → 2026-10-02, `process-contracts` 2026-10-04
+ * → 2026-10-27, `toolchain-and-build` 2026-10-01 → 2026-10-16. The other four
+ * agree with their content. (An earlier reading on 2026-09-17 listed six
+ * discrepancies including three header-LATER ones; the corpus has been
+ * hand-consolidated since, so re-measure rather than trusting either list.)
  *
  * Before the advisory moved above the skip branch it reached only the 3
  * 1:1-mappable files, which structurally excluded the four merged-prose files —
@@ -134,11 +169,77 @@ const MS_PER_DAY = 86_400_000;
 
 const PAIR_KEY_RE = /^- learning-key:\s*`([^`]+)`/;
 const PAIR_ID_RE = /^- learning-id:\s*`([^`]+)`(.*)$/;
-const COUNTER_RE = /^\*\*`expires-at` (\S+) = the EARLIEST of the (\d+) absorbed dates\*\*/;
+
+/**
+ * The recognised spellings of the body counter sentence, each with the date as
+ * capture 1 and the absorbed-pair count as capture 2, in that order.
+ *
+ * The `d` flag is load-bearing: {@link spliceCounterLine} rewrites the line by
+ * replacing exactly the two captured SPANS, so every other byte — the wording,
+ * the language, any trailing clause — survives a rewrite untouched. That is why
+ * a second language costs one entry here and no re-templating anywhere: a
+ * template would silently translate a German sentence into English on the first
+ * header raise.
+ *
+ * English is this repo's own form (all 7 live consolidated files, measured
+ * 2026-09-20 @ 9b118cf6: `grep -n 'EARLIEST of the' .claude/rules/*.md` → 7
+ * hits, `grep -rn 'FRUEHESTE\|FRÜHESTE' .claude/rules/` → 0). German is the
+ * consumer-side form reported from EventDrop.at (GH#70, 2026-09-20), where a
+ * raise lifted the frontmatter and left the body sentence claiming the older
+ * date — the sentence that literally forbids correcting it upward.
+ *
+ * @type {readonly RegExp[]}
+ */
+const COUNTER_FORMS = Object.freeze([
+  /^\*\*`expires-at` (\S+) = the EARLIEST of the (\d+) absorbed dates\*\*/d,
+  /^\*\*`expires-at` (\S+) = das FR(?:UE|Ü)HESTE der (\d+) aufgenommenen Daten\*\*/d,
+]);
+
 const HEADING_PREFIX = '### ';
 const PROVENANCE_HEADING = '## Provenance';
 const UNTRUSTED_END = '<!-- untrusted-content:end -->';
 
+/**
+ * Match one line against every recognised counter-sentence form.
+ *
+ * @param {string} line
+ * @returns {{date: string, count: number, match: RegExpExecArray}|null}
+ */
+function matchCounterLine(line) {
+  for (const form of COUNTER_FORMS) {
+    const m = form.exec(line);
+    if (m) return { date: m[1], count: Number(m[2]), match: m };
+  }
+  return null;
+}
+
+/**
+ * Rewrite a counter-sentence line to a new date and count by splicing the two
+ * captured spans, leaving every other byte — wording, language, trailing text —
+ * exactly as authored.
+ *
+ * Splices BACK-TO-FRONT (count before date) so the earlier capture's indices
+ * stay valid while the later text is replaced.
+ *
+ * @param {string} line   the line as it stands in the file
+ * @param {string} date   `YYYY-MM-DD` to write
+ * @param {number} count  the absorbed-pair count to write
+ * @returns {string} the rewritten line, or `line` unchanged when no form matches
+ */
+function spliceCounterLine(line, date, count) {
+  const hit = matchCounterLine(line);
+  if (!hit) return line;
+  const [dateStart, dateEnd] = hit.match.indices[1];
+  const [countStart, countEnd] = hit.match.indices[2];
+  return (
+    line.slice(0, dateStart) +
+    date +
+    line.slice(dateEnd, countStart) +
+    String(count) +
+    line.slice(countEnd)
+  );
+}
+
 /**
  * Parse a consolidated machine-generated rule file into its editable parts.
  *
@@ -193,11 +294,11 @@ export function parseConsolidatedRule(content) {
   const bodyStart = frontmatterEnd >= 0 ? frontmatterEnd + 1 : 0;
   for (let i = bodyStart; i < lines.length; i += 1) {
     if (counterLine === -1) {
-      const m = COUNTER_RE.exec(lines[i]);
-      if (m) {
+      const hit = matchCounterLine(lines[i]);
+      if (hit) {
         counterLine = i;
-        counterDate = m[1];
-        counterCount = Number(m[2]);
+        counterDate = hit.date;
+        counterCount = hit.count;
         continue;
       }
     }
@@ -292,6 +393,51 @@ function dateOnly(iso) {
   return String(iso).slice(0, 10);
 }
 
+/**
+ * The earliest resolvable absorbed date on the file, as `YYYY-MM-DD`.
+ *
+ * Population: EVERY provenance pair whose `learning-id` resolves to a parseable
+ * `expires_at`, markers-only pairs included — an absorbed date stays absorbed
+ * after its prose is gone, which is exactly what the body sentence's `N` counts.
+ * Unresolvable ids contribute nothing (they are reported separately as
+ * `unresolvedPairIds`), so a file whose ids all fail to resolve yields `null`
+ * rather than a guess.
+ *
+ * @param {ReturnType<typeof parseConsolidatedRule>} parsed
+ * @param {Map<string, string>} expiryById
+ * @returns {string|null}
+ */
+function earliestResolvableDate(parsed, expiryById) {
+  const dates = parsed.pairs
+    .map((p) => expiryById.get(p.id))
+    .filter((v) => typeof v === 'string' && Number.isFinite(Date.parse(v)))
+    .sort();
+  return dates.length > 0 ? dateOnly(dates[0]) : null;
+}
+
+/**
+ * The date to RAISE a too-low header to, or `null` when there is nothing to do.
+ *
+ * One-directional by contract: returns a date only when the header expires
+ * STRICTLY EARLIER than the earliest resolvable absorbed date. A header that
+ * outlives its content is never lowered here — see the module header for why
+ * the two directions are not symmetric.
+ *
+ * @param {ReturnType<typeof parseConsolidatedRule>} parsed
+ * @param {Map<string, string>} expiryById
+ * @returns {string|null}
+ */
+function headerRaiseTarget(parsed, expiryById) {
+  if (!parsed.expiresAt || parsed.expiresAtLine < 0) return null;
+  const headerMs = Date.parse(parsed.expiresAt);
+  if (!Number.isFinite(headerMs)) return null;
+  const earliest = earliestResolvableDate(parsed, expiryById);
+  if (earliest === null) return null;
+  const earliestMs = Date.parse(earliest);
+  if (!Number.isFinite(earliestMs) || earliestMs <= headerMs) return null;
+  return earliest;
+}
+
 /**
  * The header-vs-content discrepancy, as a one-line advisory string.
  *
@@ -312,16 +458,71 @@ function dateOnly(iso) {
  */
 function headerAdvisory(parsed, expiryById) {
   if (!parsed.expiresAt) return undefined;
-  const dates = parsed.pairs
-    .map((p) => expiryById.get(p.id))
-    .filter((v) => typeof v === 'string' && Number.isFinite(Date.parse(v)))
-    .sort();
-  if (dates.length === 0) return undefined;
-  const earliest = dateOnly(dates[0]);
-  if (earliest === parsed.expiresAt) return undefined;
+  const earliest = earliestResolvableDate(parsed, expiryById);
+  if (earliest === null || earliest === parsed.expiresAt) return undefined;
   return `header expires-at ${parsed.expiresAt} != earliest resolvable absorbed date ${earliest}`;
 }
 
+/**
+ * Rewrite ONLY the two dated header lines — the frontmatter `expires-at:` and
+ * the `COUNTER_RE` body sentence. Every other byte of the file is carried over
+ * untouched; that byte-identity is the whole safety argument for making a raise
+ * a rewrite trigger, and it is pinned by a test.
+ *
+ * @param {ReturnType<typeof parseConsolidatedRule>} parsed
+ * @param {string} target  `YYYY-MM-DD` to raise the header to
+ * @returns {string}
+ */
+function rewriteHeaderOnly(parsed, target) {
+  const lines = [...parsed.lines];
+  if (parsed.expiresAtLine >= 0) lines[parsed.expiresAtLine] = `expires-at: ${target}`;
+  if (parsed.counterLine >= 0) {
+    lines[parsed.counterLine] = spliceCounterLine(
+      lines[parsed.counterLine],
+      target,
+      parsed.pairs.length,
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * The plan for a file with NO expired entry: a byte-identical `keep`, or — when
+ * the header sits below the earliest absorbed date — a minimal `header-raise`
+ * rewrite. Shared by both no-expiry branches (the `no-1to1-mapping` skip and
+ * the ordinary nothing-expired case) because the raise needs no entry↔pair
+ * mapping.
+ *
+ * @param {object} base        the common plan fields
+ * @param {ReturnType<typeof parseConsolidatedRule>} parsed
+ * @param {string|undefined} advisory
+ * @param {string|null} raiseTo
+ * @returns {object}
+ */
+function keepOrRaisePlan(base, parsed, advisory, raiseTo) {
+  if (raiseTo === null) {
+    return {
+      ...base,
+      action: 'keep',
+      newExpiresAt: null,
+      newAbsorbedCount: parsed.pairs.length,
+      bytesAfter: base.bytesBefore,
+      ...(advisory ? { advisory } : {}),
+    };
+  }
+  const nextContent = rewriteHeaderOnly(parsed, raiseTo);
+  return {
+    ...base,
+    action: 'rewrite',
+    reason: 'header-raise',
+    newExpiresAt: raiseTo,
+    newAbsorbedCount: parsed.pairs.length,
+    bytesAfter: Buffer.byteLength(nextContent, 'utf8'),
+    nextContent,
+    ...(advisory ? { advisory } : {}),
+  };
+}
+
 /**
  * Plan the sweep over every machine-generated rule file. Reads only.
  *
@@ -387,25 +588,65 @@ export async function planRuleExpirySweep(opts = {}) {
     // never receive one. Measured 2026-09-17: the advisory reached 3 of 7 files
     // where 6 of 7 have the discrepancy.
     const advisory = headerAdvisory(parsed, expiryById);
+    const raiseTo = headerRaiseTarget(parsed, expiryById);
+
+    if (parsed.counterLine === -1) {
+      // FAIL-CLOSED (GH#70). Every write this module performs moves the
+      // frontmatter `expires-at` AND the body sentence that restates it. When
+      // the sentence is in a spelling {@link COUNTER_FORMS} does not recognise,
+      // the header still moves and the sentence does not — and that sentence
+      // literally says the date must not be corrected upward, so the file ships
+      // a header contradicting its own body to every agent that loads it
+      // (measured on a consumer's corpus: header 2026-11-01 beside a body
+      // claiming 2026-10-19). A second regex alone only moves the defect to the
+      // next language; refusing to write is what holds for ALL of them.
+      //
+      // The refusal covers `delete` too, not only the two rewrite triggers: the
+      // counter sentence is part of the consolidated-rule contract
+      // (`docs/rule-authoring.md` § Consolidated rules point 2), so a file
+      // without a recognised one is a shape this sweep does not understand, and
+      // `delete` is its most destructive action. Report it, touch nothing.
+      skipped.push({ file: rule.file, reason: 'no-counter-sentence' });
+      plans.push(
+        keepOrRaisePlan(
+          {
+            file: rule.file,
+            expiredPairIds: [],
+            keptPairIds: substantive.map((p) => p.id),
+            unresolvedPairIds: substantive.filter((p) => !expiryById.has(p.id)).map((p) => p.id),
+            bytesBefore: Buffer.byteLength(content, 'utf8'),
+            headings: parsed.entries.length,
+            substantivePairs: substantive.length,
+          },
+          parsed,
+          advisory,
+          null, // never raise: the body sentence cannot be kept in agreement
+        ),
+      );
+      continue;
+    }
 
     if (parsed.entries.length !== substantive.length) {
-      // FAIL-OPEN (decision 3): report, never guess. A skipped file still
-      // carries its advisory — reporting is all this branch can do.
+      // FAIL-OPEN (decision 3): report, never guess — the PROSE sweep touches
+      // nothing here. A skipped file still carries its advisory, and still gets
+      // a too-low header raised: neither needs an entry↔pair mapping.
       skipped.push({ file: rule.file, reason: 'no-1to1-mapping' });
-      plans.push({
-        file: rule.file,
-        action: 'keep',
-        expiredPairIds: [],
-        keptPairIds: substantive.map((p) => p.id),
-        unresolvedPairIds: substantive.filter((p) => !expiryById.has(p.id)).map((p) => p.id),
-        newExpiresAt: null,
-        newAbsorbedCount: parsed.pairs.length,
-        bytesBefore: Buffer.byteLength(content, 'utf8'),
-        bytesAfter: Buffer.byteLength(content, 'utf8'),
-        headings: parsed.entries.length,
-        substantivePairs: substantive.length,
-        ...(advisory ? { advisory } : {}),
-      });
+      plans.push(
+        keepOrRaisePlan(
+          {
+            file: rule.file,
+            expiredPairIds: [],
+            keptPairIds: substantive.map((p) => p.id),
+            unresolvedPairIds: substantive.filter((p) => !expiryById.has(p.id)).map((p) => p.id),
+            bytesBefore: Buffer.byteLength(content, 'utf8'),
+            headings: parsed.entries.length,
+            substantivePairs: substantive.length,
+          },
+          parsed,
+          advisory,
+          raiseTo,
+        ),
+      );
       continue;
     }
 
@@ -443,16 +684,11 @@ export async function planRuleExpirySweep(opts = {}) {
     };
 
     if (expired.length === 0) {
-      // Byte-identical. The header/earliest discrepancy is REPORTED, never
-      // silently repaired — see the module header.
-      plans.push({
-        ...base,
-        action: 'keep',
-        newExpiresAt: null,
-        newAbsorbedCount: parsed.pairs.length,
-        bytesAfter: base.bytesBefore,
-        ...(advisory ? { advisory } : {}),
-      });
+      // Byte-identical, UNLESS the header sits below the earliest absorbed date
+      // — that one direction is repaired (raised), never merely reported, or the
+      // whole file falls out of injection with nothing expired. The opposite
+      // direction stays an advisory. See the module header.
+      plans.push(keepOrRaisePlan(base, parsed, advisory, raiseTo));
       continue;
     }
 
@@ -474,6 +710,7 @@ export async function planRuleExpirySweep(opts = {}) {
     plans.push({
       ...base,
       action: 'rewrite',
+      reason: 'expired-entries',
       newExpiresAt: earliest,
       newAbsorbedCount: parsed.pairs.length,
       bytesAfter: Buffer.byteLength(nextContent, 'utf8'),
@@ -505,9 +742,10 @@ function rewriteContent({ parsed, expired, earliest, nowMs }) {
   if (earliest !== null) {
     if (parsed.expiresAtLine >= 0) lines[parsed.expiresAtLine] = `expires-at: ${earliest}`;
     if (parsed.counterLine >= 0) {
-      lines[parsed.counterLine] = lines[parsed.counterLine].replace(
-        COUNTER_RE,
-        `**\`expires-at\` ${earliest} = the EARLIEST of the ${parsed.pairs.length} absorbed dates**`,
+      lines[parsed.counterLine] = spliceCounterLine(
+        lines[parsed.counterLine],
+        earliest,
+        parsed.pairs.length,
       );
     }
   }
@@ -576,6 +814,10 @@ function assertSweepable(abs, rulesDir, file) {
  * file still dedupes) rather than an unstamped learning with no file, which
  * `/reconcile` would re-propose.
  *
+ * A plan carrying `reason: 'header-raise'` is an ordinary `action: 'rewrite'`
+ * here — same guards, same atomic write, counted in `rewritten` — because it IS
+ * a write to a tracked rule file; only its `nextContent` is narrower.
+ *
  * Every rewrite and every delete passes {@link assertSweepable} first (regular
  * file, inside the rules directory, not a symlink), and every rewrite goes
  * through `atomicWriteWithBackup` rather than `writeFileSync`. A refusal is a

package/scripts/lib/reconcile/sanitize.mjs

@@ -198,8 +198,27 @@ export const LEARNING_KEY_RE = /^[a-z0-9/-]+$/;
 /** `expires-at:` — YYYY-MM-DD. A garbage value makes the loader's expiry gate FAIL OPEN. */
 export const EXPIRES_AT_RE = /^\d{4}-\d{2}-\d{2}$/;
 
-/** `learning-id` / `source-session` — rendered inside backticks, which an interior backtick would close. */
-export const PROVENANCE_TOKEN_RE = /^[A-Za-z0-9._:-]+$/;
+/**
+ * `learning-id` / `source-session` — rendered inside backticks, which an
+ * interior backtick would close.
+ *
+ * `/` is admitted since GH#71. A semantic session id is DERIVED FROM A BRANCH
+ * NAME, and branch names carry slashes — so the narrower class did not reject
+ * hostile text, it rejected a whole legitimate id family. The damage is silent
+ * and unbounded: `engine.mjs` degrades the throw to an audited rejection, so
+ * every learning from such a session is proposed on every run and rejected on
+ * every run, forever. Measured in THIS repo 2026-09-20 @ `9b118cf6`:
+ * `jq -r 'select(.session_id != null) | .session_id'
+ * .orchestrator/metrics/sessions.jsonl | grep -c '/'` → **3**, all of the
+ * `feat/operator-surface-2026-08-08-…` family; `git branch -a --format=…
+ * | grep -c '/'` → **6**. It hit two usable learnings in the reporting
+ * consumer's run (source: peer session eventdrop-at, 2026-09-20).
+ *
+ * Widening a SANITISER is only safe against a census of what the new character
+ * makes expressible at the call sites — see {@link assertNoPathEscape} for the
+ * one hazard `/` adds and for the four it does not.
+ */
+export const PROVENANCE_TOKEN_RE = /^[A-Za-z0-9._:/-]+$/;
 
 // The Unicode Control category (C0 + DEL + C1). Deliberately expressed as
 // `\p{Cc}` rather than a hand-written character class: an escape-written class
@@ -275,6 +294,51 @@ function rejection(field, why, value) {
   return new Error(`reconcile-sanitize: rejecting record — ${field} ${why} (got ${shown})`);
 }
 
+/**
+ * Reject the ONE hazard a `/` adds to a machine token: a path shape.
+ *
+ * Derived from the call sites, not from caution. Both slash-bearing patterns —
+ * {@link PROVENANCE_TOKEN_RE} and {@link LEARNING_KEY_RE} — route through
+ * {@link assertMachineToken}, so the guard lives in that ONE shared function
+ * rather than at each caller: one guard beats one-guard-per-call-site, and it
+ * covers the next caller of an EXPORTED assert by construction
+ * (`.claude/rules/build-value.md` BV-003).
+ *
+ * **What `/` does NOT make expressible**, so this guard deliberately does not
+ * re-check it (each is already structurally impossible in every pattern that
+ * admits a slash):
+ *
+ *   1. *Inline-code break-out.* Both provenance values render inside a backtick
+ *      span (`renderer.mjs:469-470`); a backtick is in no slash-bearing class.
+ *   2. *Frontmatter escape.* A newline would open a sibling top-level key — but
+ *      JS `$` without the `m` flag does not match before a trailing newline
+ *      (measured 2026-09-20: `/^[A-Za-z0-9._:-]+$/.test("abc\n")` → `false`),
+ *      so a trailing newline was and stays rejected.
+ *   3. *Wrapper forgery.* Every literal in {@link WRAPPER_FORGERY_LITERALS}
+ *      needs `<`, `>`, `#`, a space or `(` — none of them in these classes.
+ *   4. *Dangerous invisibles.* Cf code points are outside these classes too.
+ *
+ * Gated on a literal `/` being present, which makes the guard a provable no-op
+ * for every token shape accepted BEFORE the widening: without a separator there
+ * is no traversal to express, and `..` alone in a backtick span is inert text.
+ * Census over the live store 2026-09-20 @ `9b118cf6`: 0 of 263 learning-keys and
+ * 0 learning ids carry `..` or a leading `/`, so nothing legitimate is caught.
+ *
+ * @param {string} value  a value that already matched its pattern
+ * @param {string} field
+ * @returns {void}
+ * @throws {Error} on a leading `/` (absolute path) or any `..` (traversal)
+ */
+function assertNoPathEscape(value, field) {
+  if (!value.includes('/')) return;
+  if (value.startsWith('/')) {
+    throw rejection(field, 'must not start with "/" (absolute path)', value);
+  }
+  if (value.includes('..')) {
+    throw rejection(field, 'must not contain ".." (path traversal)', value);
+  }
+}
+
 /**
  * Assert that a machine value is a non-empty string matching `pattern`.
  * REJECTS (throws) rather than repairing — see the module doc's dividing line.
@@ -282,7 +346,8 @@ function rejection(field, why, value) {
  * @param {unknown} value
  * @param {{ field: string, pattern: RegExp }} opts
  * @returns {string} the value, unchanged, when it passes
- * @throws {Error} when the value is not a string or does not match `pattern`
+ * @throws {Error} when the value is not a string, does not match `pattern`, or
+ *   carries a path escape (see {@link assertNoPathEscape})
  */
 export function assertMachineToken(value, { field, pattern }) {
   if (typeof value !== 'string' || value === '') {
@@ -291,6 +356,7 @@ export function assertMachineToken(value, { field, pattern }) {
   if (!pattern.test(value)) {
     throw rejection(field, `must match ${pattern.source}`, value);
   }
+  assertNoPathEscape(value, field);
   return value;
 }