session-orchestrator 3.19.0 → 3.20.0

package/scripts/lib/reconcile/emitter.mjs

@@ -30,6 +30,7 @@
 
 import { dirname } from 'node:path';
 
+import { learningKeyOf } from '../learnings/kebab.mjs';
 import { deriveExpiresAt } from '../learnings/schema.mjs';
 
 const DAY_MS = 86400 * 1000;
@@ -44,26 +45,64 @@ const DESCRIPTION_MAX = 120;
 // shortens a healthy future one.
 const MIN_RULE_DAYS_DEFAULT = 7;
 
+// ── #1015: field-shape gates (VALIDATION, never transformation) ──────────────
+// This emitter REJECTS agent-authored values whose SHAPE cannot be serialised
+// into frontmatter safely. It deliberately does NOT escape or neutralise
+// content: neutralisation of agent text happens exactly once, in the renderer's
+// render path. Escaping here as well would double-escape the output — a defect
+// invisible to a file-level diff, because each file still looks locally correct.
+// Rejection is idempotent, so it composes safely with the renderer's sanitiser.
+
+/**
+ * Accepted shape for `learning.host_class`.
+ *
+ * `host-class` is by far the highest-escalation field this emitter copies: the
+ * renderer serialises it UNQUOTED as `host-class: <value>`, so a newline in it
+ * injects sibling TOP-LEVEL frontmatter keys. An injected `alwaysApply: true`
+ * plus `expires-at: 2099-01-01` converts a scoped, expiring auto-generated rule
+ * into a permanent always-on one — defeating BOTH the never-always-on
+ * brandmauer below AND the expiry sweep, because each of those inspects the
+ * emitter's in-memory values rather than the serialised document.
+ *
+ * `validateLearning` (scripts/lib/learnings/schema.mjs) only asserts "string or
+ * null" for this field — ANY string, newlines included — and
+ * `validateProposalRecord` performs no unknown-key rejection, so every key on a
+ * proposal record is spread verbatim into the learning
+ * (scripts/lib/memory-proposals/sink.mjs). That is the mechanism that makes an
+ * attacker-shaped `host_class` reachable at all; this gate is where it stops.
+ *
+ * The pattern admits every value `classifyHost()` in scripts/lib/host-identity.mjs
+ * can produce (`macos-arm64-m4pro`, `linux-x86_64`, `windows-arm64`,
+ * `<osName>-<arch>`) with generous headroom, and rejects everything that could
+ * alter frontmatter structure: control chars, whitespace, `:`, `#`, quotes, and
+ * a leading `-` (a YAML sequence marker). The 64-char ceiling bounds the emitted
+ * line; the longest real value today is 17 chars, so the ceiling is inert in
+ * practice. Revisit if a future host taxonomy needs richer tokens.
+ */
+const HOST_CLASS_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+// Characters that make a `file_paths[]` entry unsafe to serialise as a glob.
+// The renderer emits each glob as `  - "<value>"`, so a control char (a newline
+// above all) breaks out of the block sequence into new top-level frontmatter
+// keys, and a quote character breaks out of the quoted scalar. Entries carrying
+// either are SKIPPED — the same defense-in-depth posture as the
+// glob-metacharacter guard below, and for the same reason: this emitter also
+// processes learnings.jsonl records that predate the #900 argv/schema guards.
+const UNSAFE_PATH_QUOTE_RE = /["']/;
+
 // Control chars: C0 range (U+0000–U+001F, includes \n \r \t) plus DEL (U+007F).
 // A newline in frontmatter would corrupt the YAML parse — stripping these is
 // critical. Written with \u escapes so the source stays pure ASCII.
 // eslint-disable-next-line no-control-regex
 const CONTROL_CHARS_RE = /[\u0000-\u001F\u007F]/g;
 
-/**
- * Slugify a string into a stable kebab-case token.
- * Lowercases, collapses every run of non-`[a-z0-9]` chars into a single `-`,
- * and trims leading/trailing `-`. UUID subjects produce ugly-but-stable keys.
- *
- * @param {string} s
- * @returns {string}
- */
-function kebab(s) {
-  return String(s)
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
+// Non-global twin of CONTROL_CHARS_RE for stateless `.test()` calls. A /g regex
+// carries `lastIndex` across calls, so testing with CONTROL_CHARS_RE directly
+// would alternate true/false on identical input. Derived from the same `.source`
+// so the two can never drift — and so this line stays pure ASCII (a literal
+// control char here would be a NUL-class corruption; see
+// .claude/rules/proven-pattern-nul-byte-corruption...).
+const CONTROL_CHARS_TEST_RE = new RegExp(CONTROL_CHARS_RE.source);
 
 // Glob metacharacters (issue #900-follow-up, Q3-MED). A top-level
 // (dirname==='.') file_paths entry is emitted AS THE GLOB ITSELF below — so a
@@ -83,8 +122,11 @@ const GLOB_METACHAR_RE = /[*?[\]{}]/;
  * the file sits at the repo top level (`dirname` === '.'), emit the bare
  * basename pattern instead of `./**` (e.g. `"foo.mjs"`). Entries containing a
  * glob metacharacter (`* ? [ ] { }`) are skipped entirely — see
- * {@link GLOB_METACHAR_RE}. Results are deduped, order-preserving on first
- * occurrence.
+ * {@link GLOB_METACHAR_RE} — as are entries carrying a control char or a quote
+ * character, which would break out of the renderer's `  - "<glob>"` sequence
+ * item into new top-level frontmatter keys (#1015; see
+ * {@link CONTROL_CHARS_TEST_RE} / {@link UNSAFE_PATH_QUOTE_RE}). Results are
+ * deduped, order-preserving on first occurrence.
  *
  * @param {string[]} filePaths
  * @returns {string[]}
@@ -95,6 +137,9 @@ function globsFromFilePaths(filePaths) {
   for (const raw of filePaths) {
     if (typeof raw !== 'string' || raw === '') continue;
     if (GLOB_METACHAR_RE.test(raw)) continue;
+    // #1015: frontmatter-structure guard. Skipping (never escaping) keeps this
+    // idempotent and non-overlapping with the renderer's sanitiser.
+    if (CONTROL_CHARS_TEST_RE.test(raw) || UNSAFE_PATH_QUOTE_RE.test(raw)) continue;
     const normalized = raw.replace(/\\/g, '/');
     const dir = dirname(normalized);
     const pattern = dir === '.' ? normalized : `${dir}/**`;
@@ -218,6 +263,9 @@ function computeExpiresAt(learning, ruleExpiryDays, now, minRuleDays) {
  * }}
  * @throws {Error} when no activation axis can be produced (empty globs AND no
  *   hostClass) — the never-always-on invariant.
+ * @throws {Error} when the learning has no derivable `learning_key` (no usable
+ *   `type`, or no `title`/`subject` that slugs to a non-empty token) — a rule
+ *   whose key resolves to no learning is worse than no rule.
  */
 export function toActivationMetadata(learning, { ruleExpiryDays, now, minRuleDays } = {}) {
   if (learning === null || typeof learning !== 'object' || Array.isArray(learning)) {
@@ -227,10 +275,25 @@ export function toActivationMetadata(learning, { ruleExpiryDays, now, minRuleDay
   const filePaths = Array.isArray(learning.file_paths) ? learning.file_paths : [];
   const globs = globsFromFilePaths(filePaths);
 
-  const hostClass =
-    typeof learning.host_class === 'string' && learning.host_class !== ''
-      ? learning.host_class
-      : undefined;
+  // #1015: `host_class` is copied straight into an UNQUOTED `host-class:`
+  // frontmatter line by the renderer, so its SHAPE is load-bearing. Reject a
+  // malformed value loudly rather than degrade to "no host axis" — a
+  // structurally-invalid host_class is a corruption/injection signal, and
+  // silently emitting the rest of the rule from the same record would hide it.
+  // The engine wraps each learning in its own try/catch, so this throw degrades
+  // to ONE recorded rejection with an auditable reason, never a crashed run.
+  let hostClass;
+  if (typeof learning.host_class === 'string' && learning.host_class !== '') {
+    if (!HOST_CLASS_RE.test(learning.host_class)) {
+      throw new Error(
+        `emitter: host_class has an unsafe shape (${JSON.stringify(learning.host_class)}) — refusing to emit; ` +
+          'the renderer serialises it as an unquoted `host-class:` line, so a newline / colon / quote there ' +
+          'injects sibling top-level frontmatter keys (e.g. alwaysApply: true + a far-future expires-at), ' +
+          `defeating the never-always-on brandmauer and the expiry sweep. Expected ${HOST_CLASS_RE.source}.`,
+      );
+    }
+    hostClass = learning.host_class;
+  }
 
   // The brandmauer: an auto-generated rule must carry ≥1 activation axis. If we
   // could derive neither a glob nor a host-class, refuse — never emit always-on.
@@ -240,8 +303,30 @@ export function toActivationMetadata(learning, { ruleExpiryDays, now, minRuleDay
     );
   }
 
-  const subjectOrTitle = learning.title || learning.subject || '';
-  const learningKey = `${learning.type}/${kebab(subjectOrTitle)}`;
+  // THE key. Derived through the shared `learningKeyOf` so the writer and every
+  // reader (engine's rejection path, validate/check-learning-provenance,
+  // learnings/candidates dedupe, claude-md-drift-check) compute one identity
+  // from one rule. This line previously kebab'd the TYPE half, which no reader
+  // does: harmless while every live type is kebab-identical, and silently
+  // divergent in both directions the moment one is not — the writer stamps one
+  // key into `.claude/rules/*.md` + `reconcile-candidates.jsonl` while every
+  // reader computes another, so dedupe stops matching with nothing failing.
+  //
+  // The injection hazard that motivated the kebab is closed downstream and
+  // LOUDLY: the key becomes an unquoted `learning-key:` frontmatter scalar, and
+  // `renderer.mjs` asserts `LEARNING_KEY_RE` (`/^[a-z0-9/-]+$/`) on it before
+  // rendering. A type carrying a newline/colon/quote is therefore rejected with
+  // an auditable reason instead of being silently re-keyed here — the same
+  // reject-don't-degrade posture as the `host_class` guard above.
+  const learningKey = learningKeyOf(learning);
+  if (learningKey === null) {
+    throw new Error(
+      'emitter: unkeyable learning (no usable type, or no title/subject that slugs to a non-empty token) — ' +
+        'refusing to emit; `learning_key` is the dedupe identity, and a record without one would either ' +
+        'stamp a rule no reader can resolve back to a learning or collide with every other unkeyable record ' +
+        'of its type.',
+    );
+  }
 
   const confidence = typeof learning.confidence === 'number' ? learning.confidence : 0;
 

package/scripts/lib/reconcile/engine.mjs

@@ -91,6 +91,7 @@
 import { readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 
+import { learningKeyOf } from '../learnings/kebab.mjs';
 import { migrateLegacyLearning, normalizeLearning } from '../learnings/schema.mjs';
 import { filterEligible } from './eligibility.mjs';
 import { toActivationMetadata } from './emitter.mjs';
@@ -180,26 +181,19 @@ function defaultLoadLearnings(repoRoot) {
 
 /**
  * Best-effort logical key for a REJECTED learning (rejections never run the
- * emitter, so there is no metadata.learningKey). Mirrors the emitter's key
- * shape `${type}/${kebab(subject||title)}` when both halves are present; falls
- * back to `null` when the type or subject/title is unusable. Never throws.
+ * emitter, so there is no `metadata.learningKey`). Delegates to the shared
+ * `learningKeyOf` — it must NOT merely "mirror" the emitter's shape, it has to
+ * BE it: this key is written to `reconcile-candidates.jsonl` and folded into
+ * `makeCandidateId`, so a learning that succeeds one run and is rejected the
+ * next would otherwise appear in the sidecar under two identities and defeat
+ * `isProcessed`/`mergeCandidates` dedupe. Returns `null` for an unkeyable
+ * record. Never throws.
  *
  * @param {unknown} learning
  * @returns {string|null}
  */
 function rejectedLearningKey(learning) {
-  if (learning === null || typeof learning !== 'object' || Array.isArray(learning)) return null;
-  const rec = /** @type {Record<string, unknown>} */ (learning);
-  const type = typeof rec.type === 'string' && rec.type !== '' ? rec.type : '';
-  const subjectOrTitle =
-    (typeof rec.title === 'string' && rec.title !== '' ? rec.title : '') ||
-    (typeof rec.subject === 'string' && rec.subject !== '' ? rec.subject : '');
-  if (type === '' || subjectOrTitle === '') return null;
-  const kebab = subjectOrTitle
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return `${type}/${kebab}`;
+  return learningKeyOf(learning);
 }
 
 /**

package/scripts/lib/reconcile/renderer.mjs

@@ -23,24 +23,43 @@
  * `confidence`, `expires-at`. Glob values are always double-quoted (the loader
  * strips surrounding quotes), which keeps `*`/`[`/`{` safe.
  *
+ * ── Untrusted-input containment (issue #1015) ────────────────────────────────
+ * Every field this renderer interpolates is AGENT-AUTHORED, and the file it
+ * produces becomes a project instruction delivered to every agent in every
+ * session — permanently, with no revocation. {@link renderRule} therefore
+ * applies `sanitize.mjs` at the render point, in two modes:
+ *   - MACHINE values (`description`, `globs[]`, `host-class`, `learning-key`,
+ *     `confidence`, `expires-at`, `id`, `source_session`) are ASSERTED and the
+ *     record REJECTED (throw) on any violation — never silently repaired.
+ *   - PROSE (`title`/`subject`, `insight`, `evidence`) is stripped of
+ *     unambiguous non-content, hard-capped in bytes, and FRAMED in the
+ *     `untrusted-content` envelope that states it is data, not instruction.
+ * The guard lives HERE and not only in the emitter for the same reason the
+ * brandmauer is re-checked below: `renderRule` is exported and callable with
+ * hand-built metadata, so the emitter's guards do not bind on it.
+ *
  * @module reconcile/renderer
  */
 
 import { createHash } from 'node:crypto';
 
-/**
- * Slugify a string into a stable kebab-case token: lowercases, collapses every
- * run of non-`[a-z0-9]` chars into a single `-`, and trims leading/trailing `-`.
- *
- * @param {string} s
- * @returns {string}
- */
-function kebab(s) {
-  return String(s)
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
+import { kebab } from '../learnings/kebab.mjs';
+import {
+  EVIDENCE_ITEM_MAX_BYTES,
+  EVIDENCE_MAX_BYTES,
+  EXPIRES_AT_RE,
+  HOST_CLASS_RE,
+  INSIGHT_MAX_BYTES,
+  LEARNING_KEY_RE,
+  PROVENANCE_TOKEN_RE,
+  TITLE_MAX_BYTES,
+  UNTRUSTED_BEGIN,
+  UNTRUSTED_END,
+  assertMachineToken,
+  assertSafeDescription,
+  assertSafeGlob,
+  sanitizeProse,
+} from './sanitize.mjs';
 
 /**
  * Short, stable SHA-1 prefix (first 7 hex chars) of an input string.
@@ -93,20 +112,47 @@ export function deriveSlug(learning) {
  * Array → one `- ` bullet per item; string → as-is; absent/empty →
  * `(no evidence recorded)`.
  *
+ * Untrusted (#1015): every item passes through {@link sanitizeProse} with a
+ * per-bullet byte cap, and the whole region is bounded by
+ * {@link EVIDENCE_MAX_BYTES}. Items that would cross the region budget are
+ * dropped with a machine-emitted note — visibly, never silently. Because
+ * `EVIDENCE_ITEM_MAX_BYTES < EVIDENCE_MAX_BYTES` by construction, at least the
+ * first item always fits.
+ *
  * @param {unknown} evidence
  * @returns {string}
+ * @throws {Error} when an item carries a delivery-wrapper forgery literal
  */
 function renderEvidence(evidence) {
-  if (Array.isArray(evidence)) {
-    const lines = evidence
-      .filter((e) => e !== null && e !== undefined && String(e) !== '')
-      .map((e) => `- ${String(e)}`);
-    return lines.length > 0 ? lines.join('\n') : '(no evidence recorded)';
+  const isArray = Array.isArray(evidence);
+  const items = isArray
+    ? evidence.filter((e) => e !== null && e !== undefined && String(e) !== '')
+    : typeof evidence === 'string' && evidence !== ''
+      ? [evidence]
+      : [];
+
+  if (items.length === 0) return '(no evidence recorded)';
+
+  /** @type {string[]} */
+  const lines = [];
+  let usedBytes = 0;
+  for (const item of items) {
+    const safe = sanitizeProse(item, { field: 'evidence', maxBytes: EVIDENCE_ITEM_MAX_BYTES });
+    const line = isArray ? `- ${safe}` : safe;
+    const width = Buffer.byteLength(line, 'utf8');
+    if (lines.length > 0 && usedBytes + width > EVIDENCE_MAX_BYTES) break;
+    lines.push(line);
+    usedBytes += width;
   }
-  if (typeof evidence === 'string' && evidence !== '') {
-    return evidence;
+
+  const omitted = items.length - lines.length;
+  if (omitted > 0) {
+    lines.push(
+      `- […${omitted} further evidence item(s) omitted by the reconciliation engine: ${EVIDENCE_MAX_BYTES}-byte region cap]`,
+    );
   }
-  return '(no evidence recorded)';
+
+  return lines.join('\n');
 }
 
 /**
@@ -120,6 +166,14 @@ function renderEvidence(evidence) {
  * @returns {{ slug: string, path: string, content: string }}
  * @throws {Error} when `metadata.globs` is empty AND `metadata.hostClass` is
  *   falsy — the never-always-on invariant (defends the emitter's guard).
+ * @throws {Error} (`reconcile-sanitize: rejecting record — …`) when a machine
+ *   value is malformed (a `description` with a control char, a dangerous
+ *   invisible, a wrapper-forgery literal or over its byte budget; a `globs[]`
+ *   element with a quote/control char/invisible; a non-token
+ *   `host-class`/`learning-key`/`id`/`source_session`; a non-finite
+ *   `confidence`; a non-`YYYY-MM-DD` `expires-at`) or when prose forges the
+ *   delivery wrapper's framing — issue #1015. The record is REJECTED, never
+ *   repaired.
  */
 export function renderRule(learning, metadata) {
   if (metadata === null || typeof metadata !== 'object' || Array.isArray(metadata)) {
@@ -139,18 +193,59 @@ export function renderRule(learning, metadata) {
     );
   }
 
+  // ── Machine-value gate (#1015) — assert, never repair ─────────────────────
+  // Each of these is serialised into a frontmatter scalar (or, for the last
+  // two, into an inline-code span). A violation REJECTS the whole record: the
+  // engine catches the throw and records an audited `emit/render error: …`
+  // rejection, so a hostile record costs one rejected proposal, never a rule
+  // file. Repairing instead of rejecting would invent information — see
+  // `sanitize.mjs` for the per-field reasoning.
+  // `description` is the ONE agent-authored value emitted outside the untrusted
+  // envelope (a frontmatter scalar cannot carry the envelope's HTML comment —
+  // the loader would read the comment AS the description). It therefore gets
+  // equivalent neutralisation instead of framing: no frontmatter escape, no
+  // smuggled invisibles, no delivery-wrapper forgery, bounded length. See
+  // `sanitize.mjs` § assertSafeDescription.
+  assertSafeDescription(metadata.description);
+  for (const glob of globs) assertSafeGlob(glob);
+  if (hostClass !== undefined) {
+    assertMachineToken(hostClass, { field: 'host-class', pattern: HOST_CLASS_RE });
+  }
+  assertMachineToken(metadata.learningKey, { field: 'learning-key', pattern: LEARNING_KEY_RE });
+  if (!Number.isFinite(metadata.confidence)) {
+    // A non-finite confidence is SILENTLY DROPPED by the loader's `Number(...)`
+    // coercion, so the rule would load with no confidence at all rather than
+    // fail loudly.
+    throw new Error(
+      `reconcile-sanitize: rejecting record — confidence must be a finite number (got ${JSON.stringify(metadata.confidence)})`,
+    );
+  }
+  assertMachineToken(metadata.expiresAt, { field: 'expires-at', pattern: EXPIRES_AT_RE });
+
   const slug = deriveSlug(learning);
   const path = `.claude/rules/${slug}.md`;
 
-  const humanTitle =
+  // Prose sources. `deriveSlug` is safe by construction (its `kebab` collapses
+  // every non-`[a-z0-9]` run, so no title can steer the output path), but the
+  // rendered H1 carries the raw value — `title` outranks `subject` and has no
+  // schema constraint at all, so it is capped and framed like any other prose.
+  const rawTitle =
     (typeof learning.title === 'string' && learning.title !== '' ? learning.title : '') ||
     (typeof learning.subject === 'string' && learning.subject !== '' ? learning.subject : '') ||
     metadata.learningKey ||
     slug;
+  const safeTitle = sanitizeProse(rawTitle, { field: 'title', maxBytes: TITLE_MAX_BYTES })
+    // The H1 is a single line: a newline in the title would end the heading and
+    // let the remainder render as top-level markdown of the attacker's choosing.
+    .replace(/[\t\n]+/g, ' ')
+    .trim();
+  // A title made only of stripped invisibles sanitises to '' — fall back to the
+  // slug so the H1 is never empty.
+  const humanTitle = safeTitle !== '' ? safeTitle : slug;
 
   const insight =
     typeof learning.insight === 'string' && learning.insight !== ''
-      ? learning.insight
+      ? sanitizeProse(learning.insight, { field: 'insight', maxBytes: INSIGHT_MAX_BYTES })
       : '(no insight recorded)';
 
   // ── Frontmatter (fixed key order; loader-parseable) ──────────────────────
@@ -182,11 +277,30 @@ export function renderRule(learning, metadata) {
   fm.push('---');
 
   // ── Body (free markdown; does not affect frontmatter parsing) ────────────
-  const learningId = learning.id ? String(learning.id) : 'n/a';
-  const sourceSession = learning.source_session ? String(learning.source_session) : 'n/a';
+  // Both provenance values are rendered INSIDE an inline-code span below, which
+  // an interior backtick would close — so they are asserted as machine tokens
+  // rather than escaped. The 'n/a' fallbacks are machine-emitted, not asserted.
+  const learningId = learning.id
+    ? assertMachineToken(String(learning.id), {
+        field: 'learning-id',
+        pattern: PROVENANCE_TOKEN_RE,
+      })
+    : 'n/a';
+  const sourceSession = learning.source_session
+    ? assertMachineToken(String(learning.source_session), {
+        field: 'source-session',
+        pattern: PROVENANCE_TOKEN_RE,
+      })
+    : 'n/a';
 
+  // The untrusted region (H1 + insight + Evidence) is FRAMED: the envelope
+  // states, in machine-generated text the record cannot forge, that everything
+  // inside is agent-authored data rather than an instruction to the reading
+  // agent. Provenance stays OUTSIDE the envelope — it is machine-derived and
+  // asserted above.
   const body = [
     '',
+    UNTRUSTED_BEGIN,
     `# Auto-generated rule: ${humanTitle}`,
     '',
     insight,
@@ -194,6 +308,8 @@ export function renderRule(learning, metadata) {
     '## Evidence',
     renderEvidence(learning.evidence),
     '',
+    UNTRUSTED_END,
+    '',
     '<!-- provenance (auto-generated by the reconciliation engine — do not hand-edit) -->',
     '## Provenance',
     `- learning-key: \`${metadata.learningKey}\``,