session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/state-md/yaml-parser.mjs

@@ -6,8 +6,15 @@
  *   - Flow-style integer arrays (`[1, 2, 3]`)
  *   - Block-style sequences of mappings (issue #244), e.g. `docs-tasks:` with
  *     indented `- key: value` entries. Only one nesting level supported.
+ *   - Single-line FLOW MAPPINGS as list items (`- { k: v, … }`) — hand-written
+ *     but valid YAML, parsed into the same plain object a block item yields and
+ *     re-emitted in block notation on the next serialize (#1111).
  *
  * That is the full grammar permitted by skills/_shared/state-ownership.md.
+ * A list item this grammar cannot represent (a flow SEQUENCE `- [a, b]`, or a
+ * flow mapping whose interior is malformed) is dropped from ITS OWN LIST and
+ * reported on `parseStateMd(...).warnings` — never escalated to a null
+ * document. See `parseBlockValue` for why that scoping is load-bearing.
  *
  * Never throws. Returns null for unparseable input rather than raising.
  *
@@ -35,17 +42,28 @@ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 /**
  * Parses a STATE.md file into frontmatter + body.
  *
+ * `warnings` is OMITTED (not `null`, not `[]`) when the parse was clean, so a
+ * caller pinning the whole return with `toEqual({ frontmatter, body })` still
+ * matches and no consumer has to learn about it to keep working. When present
+ * it is a non-empty array of `{ key, index, reason }` records naming list items
+ * that were dropped from `frontmatter[key]` — `index` addresses the RAW source
+ * item position (dropped items included), so it stays quotable against the file
+ * even though the surviving array is shorter.
+ *
  * @param {string} contents
- * @returns {{frontmatter: object, body: string}|null}
+ * @returns {{frontmatter: object, body: string, warnings?: Array<{key: string, index: number, reason: string}>}|null}
  */
 export function parseStateMd(contents) {
   if (typeof contents !== 'string') return null;
   const match = FRONTMATTER_RE.exec(contents);
   if (!match) return null;
   const [, fmText, body] = match;
-  const frontmatter = parseFrontmatter(fmText);
+  const warnings = [];
+  const frontmatter = parseFrontmatter(fmText, warnings);
   if (frontmatter === null) return null;
-  return { frontmatter, body: body.startsWith('\n') ? body.slice(1) : body };
+  const parsed = { frontmatter, body: body.startsWith('\n') ? body.slice(1) : body };
+  if (warnings.length > 0) parsed.warnings = warnings;
+  return parsed;
 }
 
 /**
@@ -70,7 +88,7 @@ export function serializeStateMd({ frontmatter, body }) {
   return `---\n${fmLines.join('\n')}\n---\n${bodyOut}`;
 }
 
-function parseFrontmatter(text) {
+function parseFrontmatter(text, warnings) {
   const out = {};
   const lines = text.split(/\r?\n/);
   let i = 0;
@@ -87,7 +105,7 @@ function parseFrontmatter(text) {
     if (key === '') return null;
     const valuePart = rstripped.slice(idx + 1).trim();
     if (valuePart === '') {
-      const result = parseBlockValue(lines, i + 1);
+      const result = parseBlockValue(lines, i + 1, key, warnings);
       if (result === null) return null;
       out[key] = result.value;
       i = result.nextIndex;
@@ -106,8 +124,27 @@ function parseFrontmatter(text) {
  *     no body) and `nextIndex === start` so the caller resumes at `start`.
  *   - `value === [...]` means a block sequence was consumed.
  * Returns `null` on malformed block syntax.
+ *
+ * A list item that opens a YAML FLOW collection is resolved PER ITEM, never per
+ * document:
+ *   - `- { id: m-1, task: "x", wave: 1, status: b }` parses into exactly the
+ *     object the equivalent block item yields (and serializes back as block
+ *     notation). Splitting it at the first colon — the #1111 bug, measured
+ *     2026-08-24 @ f0766e1 as `keys: ["{ id"] · status: undefined` — is what
+ *     this must never do again.
+ *   - Anything else flow-shaped (`- [a, b]`, or a `{ … }` whose interior is
+ *     malformed) is dropped from THIS list with a `warnings` record. It cannot
+ *     be kept: a non-mapping item makes `isBlockSeqOfMappings` false for the
+ *     whole array, and the serializer would then emit the entire list through
+ *     `serializeScalar` as `[object Object]`.
+ *
+ * Escalating either case to `null` for the WHOLE document — the first #1111 fix
+ * — is the failure this scoping exists to prevent: every mutator in this family
+ * opens with `parseStateMd(contents); if (parsed === null) return contents;`, so
+ * one hand-written item silently turned every STATE.md write into a no-op that
+ * reported success. Silent-wrong must not be traded for silent-absent.
  */
-function parseBlockValue(lines, start) {
+function parseBlockValue(lines, start, key, warnings) {
   let i = start;
   while (i < lines.length) {
     const rstripped = lines[i].replace(/\s+$/, '');
@@ -124,6 +161,7 @@ function parseBlockValue(lines, start) {
   const indent = bulletMatch[1];
   const contIndent = indent + '  ';
   const entries = [];
+  let itemIndex = 0;
   while (i < lines.length) {
     const rstripped = lines[i].replace(/\s+$/, '');
     if (rstripped === '' || /^\s*#/.test(rstripped)) {
@@ -132,12 +170,26 @@ function parseBlockValue(lines, start) {
     }
     if (!rstripped.startsWith(indent + '- ')) break;
     const firstBody = rstripped.slice(indent.length + 2);
-    const firstColon = firstBody.indexOf(':');
-    if (firstColon === -1) return null;
-    const firstKey = firstBody.slice(0, firstColon).trim();
-    if (firstKey === '') return null;
-    const entry = {};
-    entry[firstKey] = parseScalar(firstBody.slice(firstColon + 1).trim());
+    // `entry === null` marks an item this grammar cannot represent: its
+    // continuation lines are still consumed below (so the walk stays aligned),
+    // but nothing is pushed onto `entries`.
+    let entry;
+    if (firstBody.startsWith('{')) {
+      entry = parseFlowMapping(firstBody);
+      if (entry === null) {
+        warnings.push({ key, index: itemIndex, reason: 'malformed-flow-mapping' });
+      }
+    } else if (firstBody.startsWith('[')) {
+      entry = null;
+      warnings.push({ key, index: itemIndex, reason: 'flow-sequence-item' });
+    } else {
+      const firstColon = firstBody.indexOf(':');
+      if (firstColon === -1) return null;
+      const firstKey = firstBody.slice(0, firstColon).trim();
+      if (firstKey === '') return null;
+      entry = {};
+      entry[firstKey] = parseScalar(firstBody.slice(firstColon + 1).trim());
+    }
     i++;
     while (i < lines.length) {
       const inner = lines[i].replace(/\s+$/, '');
@@ -150,16 +202,93 @@ function parseBlockValue(lines, start) {
       if (/^\s/.test(body)) return null;
       const colon = body.indexOf(':');
       if (colon === -1) return null;
-      const key = body.slice(0, colon).trim();
-      if (key === '') return null;
-      entry[key] = parseScalar(body.slice(colon + 1).trim());
+      const contKey = body.slice(0, colon).trim();
+      if (contKey === '') return null;
+      if (entry !== null) entry[contKey] = parseScalar(body.slice(colon + 1).trim());
       i++;
     }
-    entries.push(entry);
+    if (entry !== null) entries.push(entry);
+    itemIndex++;
   }
   return { value: entries, nextIndex: i };
 }
 
+/**
+ * Splits a flow-collection interior on its TOP-LEVEL commas — the ones outside
+ * quotes and outside any nested `{}`/`[]`. A naive `split(',')` would cut
+ * `task: "a, b"` in half, which is the same class of first-separator mistake
+ * that produced the `{ id` key in the first place.
+ *
+ * @param {string} inner
+ * @returns {string[]}
+ */
+function splitFlowSegments(inner) {
+  const segments = [];
+  let depth = 0;
+  let quote = null;
+  let current = '';
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (quote !== null) {
+      current += ch;
+      if (ch === '\\' && quote === '"') {
+        current += inner[++i] ?? '';
+      } else if (ch === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") quote = ch;
+    else if (ch === '{' || ch === '[') depth++;
+    else if (ch === '}' || ch === ']') depth--;
+    else if (ch === ',' && depth === 0) {
+      segments.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  segments.push(current);
+  return segments;
+}
+
+/**
+ * Parses a SINGLE-LINE YAML flow mapping (`{ k: v, k2: "v, 2" }`) into a plain
+ * object, reusing `parseScalar` for each value so a flow item and the equivalent
+ * block item yield byte-identical results.
+ *
+ * Returns `null` when `raw` is not a well-formed single-line flow mapping —
+ * unterminated, an empty segment, or a segment with no `:`. Callers report that
+ * as a dropped item; nothing here throws.
+ *
+ * KNOWN CEILING: a NESTED flow mapping value (`{ id: m-1, meta: { a: 1 } }`)
+ * keeps `{ a: 1 }` as a STRING rather than an object — this subset has no
+ * nested-mapping representation and the serializer has no way to emit one. Flat
+ * flow mappings are the whole observed population (hand-written `mission-status`
+ * / `docs-tasks` items). Revisit if a nested flow value ever appears in a real
+ * STATE.md.
+ *
+ * @param {string} raw
+ * @returns {object|null}
+ */
+function parseFlowMapping(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) return null;
+  const inner = trimmed.slice(1, -1).trim();
+  const out = {};
+  if (inner === '') return out;
+  for (const segment of splitFlowSegments(inner)) {
+    const part = segment.trim();
+    if (part === '') return null;
+    const colon = part.indexOf(':');
+    if (colon === -1) return null;
+    const key = part.slice(0, colon).trim();
+    if (key === '') return null;
+    out[key] = parseScalar(part.slice(colon + 1).trim());
+  }
+  return out;
+}
+
 function parseScalar(raw) {
   if (raw === '' || raw === 'null' || raw === '~') return null;
   if (raw === 'true') return true;

package/scripts/lib/state-md.mjs

@@ -1,13 +1,13 @@
 /**
  * STATE.md helpers (issue #184).
  *
- * Thin barrel — re-exports all 25 public symbols from the split submodules.
+ * Thin barrel — re-exports every public symbol of the split submodules.
  * Implementation lives in scripts/lib/state-md/*.mjs.
  *
  * @see scripts/lib/state-md/yaml-parser.mjs        parseStateMd, serializeStateMd
  * @see scripts/lib/state-md/frontmatter-mutators.mjs touchUpdatedField, updateFrontmatterFields
  * @see scripts/lib/state-md/body-sections.mjs       readCurrentTask, appendDeviation, markExpressPathComplete, appendWhatNotToRetry, readWhatNotToRetry, readOpenQuestions, appendOpenQuestion, markOpenQuestionAnswered
- * @see scripts/lib/state-md/mission-status.mjs      parseMissionStatus, writeMissionStatus, setMissionStatus, readMissionStatus
+ * @see scripts/lib/state-md/mission-status.mjs      parseMissionStatus, parseMissionStatusStrict, MISSION_STATUS_VALUES, writeMissionStatus, setMissionStatus, setMissionStatusDetailed, readMissionStatus, recoverFrontmatterMissionStatusDetailed, writeMissionStatusOnDisk, setMissionStatusOnDisk
  * @see scripts/lib/state-md/recommendations.mjs     parseRecommendations
  */
 
@@ -43,11 +43,21 @@ export {
 
 export {
   parseMissionStatus,
+  // The strict reader and the status vocabulary are part of the same public
+  // surface as `parseMissionStatus` (#1111) — a consumer that imports from this
+  // barrel (the documented entry point) reached neither until this re-export
+  // landed: a static `import { parseMissionStatusStrict } from '.../state-md.mjs'`
+  // failed at link time, and the `await import()` form — the one hooks and
+  // lazy loaders use — yielded `undefined` and failed only at the call.
+  parseMissionStatusStrict,
+  MISSION_STATUS_VALUES,
   writeMissionStatus,
   setMissionStatus,
   readMissionStatus,
   writeMissionStatusOnDisk,
   setMissionStatusOnDisk,
+  recoverFrontmatterMissionStatusDetailed,
+  setMissionStatusDetailed,
 } from './state-md/mission-status.mjs';
 
 export { parseRecommendations } from './state-md/recommendations.mjs';

package/scripts/lib/telemetry/schema.mjs

@@ -220,6 +220,54 @@ export function filterRosterNames(names, rosterSet) {
   return deduped.slice(0, MAX_NAMES);
 }
 
+/**
+ * Classify a single raw invocation name into the skills or commands bucket.
+ *
+ * The Skill tool surfaces slash-commands that have NO backing `skills/` directory
+ * under the same plugin-prefixed name form as real skills (e.g.
+ * `session-orchestrator:session` for `commands/session.md`). `roster.skills` holds
+ * PREFIXED names, `roster.commands` holds BARE ones — so a prefixed command name
+ * matches neither set and used to be bucketed to 'other' (GitLab #1189: commands
+ * was `[]` in 345/345 usage pings).
+ *
+ * Decision order (skill roster wins on a spelling collision such as
+ * `memory-cleanup`, which is both a skill dir and a command file):
+ *   1. name in rosterSkills                     → {kind:'skill',   name}  (verbatim)
+ *   2. name is PREFIXED and its bare form is in rosterCommands
+ *                                               → {kind:'command', bare}
+ *   3. otherwise                                → {kind:'skill',   name}  (verbatim)
+ *
+ * Case 2 REQUIRES the plugin prefix (session-reviewer W2 finding, 2026-09-02).
+ * Without that requirement, a BARE third-party or personal skill name that
+ * happens to collide with one of our shipped command names (`test`, `close`,
+ * `go`, `release`, `portfolio` are all plausible foreign skill names) would be
+ * recorded as OUR command — a data-integrity defect, and the same rule made
+ * `memory-cleanup` reach BOTH buckets in one ping (bare → commands, prefixed →
+ * skills), double-counting a single surface. Requiring the prefix removes both:
+ * a bare arrival can only ever be a skill-path name, so an unknown one becomes
+ * 'other'. Cost: the one genuine bare `memory-cleanup` record is recorded as
+ * 'other' rather than as the command.
+ *
+ * Case 3 keeps foreign/third-party names on the SKILLS path only, where
+ * filterRosterNames projects them to the opaque token 'other' — an unclassified
+ * name is never duplicated into `commands`, preserving the privacy invariant.
+ *
+ * @param {unknown} name raw invocation name
+ * @param {Set<string>} rosterSkills prefixed shipped-skill names
+ * @param {Set<string>} rosterCommands bare shipped-command names
+ * @returns {{kind: 'skill'|'command', name: unknown}}
+ */
+export function classifyInvocationName(name, rosterSkills, rosterCommands) {
+  const skills = rosterSkills instanceof Set ? rosterSkills : new Set();
+  const commands = rosterCommands instanceof Set ? rosterCommands : new Set();
+  if (typeof name !== 'string') return { kind: 'skill', name };
+  if (skills.has(name)) return { kind: 'skill', name };
+  if (!name.startsWith(SKILL_PREFIX)) return { kind: 'skill', name };
+  const bare = name.slice(SKILL_PREFIX.length);
+  if (commands.has(bare)) return { kind: 'command', name: bare };
+  return { kind: 'skill', name };
+}
+
 // ---------------------------------------------------------------------------
 // Duration bucketing
 // ---------------------------------------------------------------------------
@@ -331,12 +379,12 @@ function distinctField(records, field) {
  * whitelist-clean but does NOT carry `anon_id` — the caller sets it via
  * ensureAnonId (anon-id.mjs), keeping ID rotation isolated there.
  *
- * skills are the distinct `.skill` values of `skillInvocations`; commands are the
- * distinct `.command` values of the same records (none in v1 skill-invocations
- * telemetry ⇒ []; the field is honored so a future command-telemetry stream feeds
- * in without a signature change). Both are roster-filtered — off-roster names
- * become "other" — deduped, sorted, and capped. No frequencies are recorded (v1
- * decision).
+ * The distinct `.skill` and `.command` values of `skillInvocations` go through a
+ * single classifyInvocationName pass that routes each name to skills or commands
+ * (the `.command` field carries nothing today; it is honored so a future direct
+ * command-telemetry stream feeds in without a signature change). Both buckets are
+ * then roster-filtered — off-roster names become "other" — deduped, sorted, and
+ * capped. No frequencies are recorded (v1 decision).
  *
  * @param {{
  *   sessionRecord: object,
@@ -362,8 +410,26 @@ export function buildUsagePing({
   const rosterSkills = rst?.skills instanceof Set ? rst.skills : new Set();
   const rosterCommands = rst?.commands instanceof Set ? rst.commands : new Set();
 
-  const skillNames = distinctField(invocations, 'skill');
-  const commandNames = distinctField(invocations, 'command');
+  // ONE classification pass over the union of both producer fields: today only
+  // `.skill` is written by hooks/skill-invocation-telemetry.mjs, `.command` is
+  // kept for the forward-compat producer documented above.
+  //
+  // `.command` records carry the BARE name, and classifyInvocationName requires
+  // the plugin prefix before it will route anything to the commands bucket (see
+  // its doc comment). So a `.command` name is normalized to the prefixed form
+  // first — the field itself is the "this is one of ours" signal that a bare
+  // `.skill` arrival lacks. Without this the forward-compat producer would be
+  // wired but dead: every record it writes would silently become 'other'.
+  const skillNames = [];
+  const commandNames = [];
+  const rawNames = [
+    ...distinctField(invocations, 'skill'),
+    ...distinctField(invocations, 'command').map((n) => (n.startsWith(SKILL_PREFIX) ? n : `${SKILL_PREFIX}${n}`)),
+  ];
+  for (const raw of rawNames) {
+    const { kind, name } = classifyInvocationName(raw, rosterSkills, rosterCommands);
+    (kind === 'command' ? commandNames : skillNames).push(name);
+  }
 
   return {
     record_kind: 'usage-ping',

package/scripts/lib/telemetry/sync.mjs

@@ -39,6 +39,7 @@ import { ensureAnonId } from './anon-id.mjs';
 import { peekAll, enqueue, clear, queueStats } from './queue.mjs';
 import { loadOwnerConfig } from '../owner-yaml.mjs';
 import { readJsonlFile } from '../io.mjs';
+import { readCanonicalSessions } from '../sessions-canonical.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -93,15 +94,51 @@ function defaultSender({ env, timeoutMs }) {
 // Batch build
 // ---------------------------------------------------------------------------
 
+/**
+ * The canonical (#1167-deduplicated) session record most recently WRITTEN to
+ * the ledger — ranked by `completed_at` (falling back to `started_at` when
+ * absent), the closest analogue to "the last line of the file" once the reader
+ * no longer trusts append order.
+ *
+ * `readCanonicalSessions` reorders its output to "first appearance of each
+ * surviving id" (see sessions-canonical.mjs's own docstring) — it is NOT
+ * append order — so a raw `records[records.length - 1]` (the pre-#1186 read)
+ * silently picks the WRONG session once a `session_id` duplicate or a
+ * `supersedes` collapse reshuffles the array. A record with neither timestamp
+ * sorts last and is never chosen over a dated one.
+ *
+ * @param {Array<object>} records — canonical session records.
+ * @returns {object|null}
+ */
+function mostRecentSession(records) {
+  let best = null;
+  let bestTs = '';
+  for (const rec of records) {
+    if (!rec || typeof rec !== 'object') continue;
+    const ts =
+      typeof rec.completed_at === 'string' && rec.completed_at
+        ? rec.completed_at
+        : typeof rec.started_at === 'string'
+          ? rec.started_at
+          : '';
+    if (ts && ts > bestTs) {
+      best = rec;
+      bestTs = ts;
+    }
+  }
+  return best;
+}
+
 /**
  * Build ONE whitelist-projected usage-ping record from the local JSONL streams.
  *
- * Reads `<metricsDir>/sessions.jsonl` + `<metricsDir>/skill-invocations.jsonl`
- * (metricsDir defaults to `<cwd>/.orchestrator/metrics`). The LAST sessions.jsonl
- * record defines the session window: skill-invocations whose `timestamp >=` its
- * `started_at` are included. When no session record exists, the ping falls back
- * to `session_type: 'other'`, `duration_bucket: '<15m'`, and the invocations of
- * the last 24 hours.
+ * Reads `<metricsDir>/sessions.jsonl` (via `readCanonicalSessions`, #1186 — the
+ * #1167 newest-wins-per-`session_id` / `supersedes` collapse) +
+ * `<metricsDir>/skill-invocations.jsonl`. The most-recently-written CANONICAL
+ * session record (`mostRecentSession`, above) defines the session window:
+ * skill-invocations whose `timestamp >=` its `started_at` are included. When no
+ * session record exists, the ping falls back to `session_type: 'other'`,
+ * `duration_bucket: '<15m'`, and the invocations of the last 24 hours.
  *
  * anon-ID handling (persist=true, the send path): `ensureAnonId` runs on the
  * telemetry.json record; a created/rotated ID is persisted via
@@ -137,10 +174,10 @@ export function buildBatch({
     const dir = metricsDir || path.join(process.cwd(), '.orchestrator', 'metrics');
     const nowIso = now || new Date().toISOString();
 
-    const sessions = readJsonlFile(path.join(dir, 'sessions.jsonl'), { skipInvalid: true });
+    const sessions = readCanonicalSessions({ filePath: path.join(dir, 'sessions.jsonl') });
     const invocations = readJsonlFile(path.join(dir, 'skill-invocations.jsonl'), { skipInvalid: true });
 
-    const sessionRecord = sessions.length > 0 ? sessions[sessions.length - 1] : null;
+    const sessionRecord = mostRecentSession(sessions);
 
     let windowInvocations;
     let sessionForPing;
@@ -287,25 +324,63 @@ export async function flush({
 // ---------------------------------------------------------------------------
 
 /**
- * Whether a daily-fallback flush is due: the queue is non-empty AND more than 24h
- * have passed since the last successful flush (a never-flushed queue with items
- * counts as due). Cheap — a single telemetry.json read + a queue stat. Never throws.
+ * Whether a daily-fallback flush is due. Two independent ways to be due, both
+ * requiring that more than 24h have passed since the last successful flush
+ * (never-flushed counts as infinitely stale):
+ *
+ *   (a) RETRY — the offline queue is non-empty: earlier sends failed and the
+ *       backlog deserves another attempt.
+ *   (b) CATCH-UP — the queue is empty, but `<metricsDir>/sessions.jsonl` ends on
+ *       a record whose `completed_at` is NEWER than `last_flush_at`: a session
+ *       closed since the last successful send and produced no ping.
+ *
+ * (b) is the reason this predicate exists at all. While it was queue-only, the
+ * "daily fallback" could ONLY re-send what had already failed to send — it could
+ * never originate a ping. Measured 2026-08-23 (#1138): 588 session closes across
+ * 13 repos produced 82 ingest records (~14%), because the ONE writer of the
+ * queue is a failed `flush()`, and a `flush()` that never runs never fails.
+ *
+ * Cheap in the common case: the staleness gate is checked FIRST (one small
+ * telemetry.json read), so a host that flushed within the last 24h returns
+ * before touching either the queue or the session ledger.
+ *
+ * Never throws.
  *
  * @param {object} [opts]
  * @param {string} [opts.statePath]  telemetry.json path override.
  * @param {string} [opts.queuePath]  queue path override.
+ * @param {string} [opts.metricsDir] Metrics dir for the (b) catch-up probe
+ *                                   (default `<cwd>/.orchestrator/metrics`).
  * @param {number} [opts.now]        Reference time in epoch-ms (default Date.now()).
  * @returns {boolean}
  */
-export function shouldDailyFlush({ statePath, queuePath, now = Date.now() } = {}) {
+export function shouldDailyFlush({ statePath, queuePath, metricsDir, now = Date.now() } = {}) {
   try {
-    const { count } = queueStats({ path: queuePath });
-    if (count <= 0) return false;
-
+    // Staleness gate — shared by BOTH disjuncts, so it runs first and short-
+    // circuits the two file probes below on every fresh host.
     const { record } = readTelemetryState({ path: statePath });
     const raw = record?.last_flush_at;
     const lastMs = typeof raw === 'string' && !Number.isNaN(Date.parse(raw)) ? Date.parse(raw) : 0;
-    return now - lastMs > DAILY_FLUSH_MS;
+    if (now - lastMs <= DAILY_FLUSH_MS) return false;
+
+    // (a) Retry an existing backlog.
+    const { count } = queueStats({ path: queuePath });
+    if (count > 0) return true;
+
+    // (b) Catch-up: a session completed after the last successful flush.
+    //     Reuses buildBatch's reader (#1186: readCanonicalSessions +
+    //     mostRecentSession) — same file, same #1167 dedupe, no second parser.
+    //
+    //     Deliberate simplification (named ceiling): this parses the WHOLE
+    //     sessions.jsonl to look at its last record. At the observed ledger size
+    //     (271 records / 292 KB in this repo, 2026-08-23) that is sub-millisecond
+    //     and it only runs once the 24h gate above has already passed. Revisit
+    //     with a tail-read if any repo's sessions.jsonl passes ~10 MB.
+    const dir = metricsDir || path.join(process.cwd(), '.orchestrator', 'metrics');
+    const sessions = readCanonicalSessions({ filePath: path.join(dir, 'sessions.jsonl') });
+    const last = mostRecentSession(sessions);
+    const completedMs = Date.parse(last?.completed_at);
+    return !Number.isNaN(completedMs) && completedMs > lastMs;
   } catch {
     return false;
   }

package/scripts/lib/tmux-layout/telemetry.mjs

@@ -19,6 +19,7 @@ import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { findProjectRoot } from '../common.mjs';
+import { stampEventSchemaVersion, validateEventRecord } from '../events-schema.mjs';
 
 /**
  * Path FRAGMENT joined against a resolved repo root at write time — NOT a
@@ -58,11 +59,22 @@ export function emit(eventType, payload = {}, { repoRoot } = {}) {
     const eventsPath = path.join(repoRoot || findProjectRoot(), ...EVENTS_REL);
     const dir = path.dirname(eventsPath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const record = {
+    // `stampEventSchemaVersion()` rather than an inline `schema_version:` —
+    // one stamper for the whole ledger (#1177). It is additive (stamps only
+    // when absent), so a payload that carries its own version still wins, and
+    // it is pure (no fs), so the sync write path below is unaffected.
+    const record = stampEventSchemaVersion({
       event: eventType,
       timestamp: new Date().toISOString(),
       ...payload,
-    };
+    });
+    // Same schema contract as emitEvent() (#1177), enforced here too because
+    // this is the ONE remaining raw writer of events.jsonl. Kept synchronous on
+    // purpose — withTelemetry() wraps sync layout code; validateEventRecord() is
+    // pure (no fs), so conformance costs no async hop. An invalid record is
+    // DROPPED rather than written: telemetry is best-effort by contract, and a
+    // malformed line would outlive this process in the shared ledger.
+    if (!validateEventRecord(record).valid) return;
     appendFileSync(eventsPath, JSON.stringify(record) + '\n');
   } catch {
     // Best-effort — swallow all errors. Telemetry must not block layout.

package/scripts/lib/validate/check-agents.mjs

@@ -10,6 +10,7 @@ import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
 import { ALLOWED_MODEL_ALIASES, MODEL_ID_RE } from '../agent-frontmatter.mjs';
 import { extractInitialFrontmatter } from './frontmatter-block.mjs';
+import { parseFrontmatterDescription } from '../description-surface.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -136,6 +137,57 @@ function parseToolsValue(toolsVal) {
   return v.split(',').map((t) => t.trim()).filter(Boolean);
 }
 
+/**
+ * Detect a `description:` whose YAML-PARSED value is a silently truncated
+ * PREFIX of what the file actually says (#1029).
+ *
+ * An unquoted (plain) YAML scalar ends at the first ` #`: everything from there
+ * on is a comment. The block still parses, so every other rule in this gate
+ * stays green while the agent picker receives a stub — `agents/eval-judge.md`
+ * shipped 51 of 1,180 characters (96% dropped, measured 2026-08-24) and nothing
+ * complained. This is the concrete case the Check-6 preamble describes in prose.
+ *
+ * Detected by COMPARISON, never by pattern: the parsed value must be a strict
+ * prefix of the raw scalar AND the dropped tail must open a comment. A
+ * legitimately quoted description whose text merely contains `#` parses in full
+ * (parsed === raw, no length gap) and is never flagged; a quoted description
+ * carrying YAML escapes diverges from its raw form and fails the prefix test.
+ *
+ * Raw extraction is delegated to `parseFrontmatterDescription` (the sibling
+ * measurement probe already owns it, block scalars and quote-stripping included)
+ * rather than re-derived from a fourth regex here.
+ *
+ * @param {string} content - the agent file's raw content
+ * @param {Record<string, unknown>} data - the parsed frontmatter mapping
+ * @param {string} frontmatter - the frontmatter block's inner text
+ * @returns {{ parsedLength: number, rawLength: number } | null} null when intact
+ */
+function detectDescriptionTruncation(content, data, frontmatter) {
+  if (!hasField(frontmatter, 'description')) return null;
+
+  // A `description:` key whose WHOLE value is a comment (`description: #803 …`)
+  // parses to null — a 0-character description, the same defect at 100% loss.
+  const parsedValue =
+    typeof data?.description === 'string'
+      ? data.description
+      : data?.description === null || data?.description === undefined
+        ? ''
+        : null;
+  if (parsedValue === null) return null;
+
+  const rawField = parseFrontmatterDescription(content);
+  // Block scalars carry no comment semantics and are rejected outright by the
+  // inline-string rule below — not this rule's business.
+  if (!rawField || rawField.isBlockScalar) return null;
+
+  const raw = rawField.raw;
+  if (raw.length <= parsedValue.length) return null;
+  if (!raw.startsWith(parsedValue)) return null;
+  if (!/(^|\s)#/.test(raw.slice(parsedValue.length))) return null;
+
+  return { parsedLength: parsedValue.length, rawLength: raw.length };
+}
+
 // ============================================================================
 // Check 6: Agent .md files have valid YAML frontmatter
 // ============================================================================
@@ -226,6 +278,20 @@ if (mdFiles.length === 0) {
     }
     parseable++;
 
+    // ------------------------------------------------------------------
+    // Prefix-truncation rule (#1029) — the ` #` case the preamble above names.
+    // Runs BEFORE the field rules: a description truncated to a stub still
+    // satisfies every one of them, so this is the only place the loss shows up.
+    // ------------------------------------------------------------------
+    const truncated = detectDescriptionTruncation(content, parsedFm.data, frontmatter);
+    if (truncated) {
+      fail(
+        `${agentName}: description is silently truncated by an unquoted ' #' — YAML parses ` +
+          `${truncated.parsedLength} of ${truncated.rawLength} chars and reads the rest as a comment; ` +
+          `quote the description (double-quoted, escaping any " inside) so the full text parses`,
+      );
+    }
+
     // ------------------------------------------------------------------
     // Required fields check
     // ------------------------------------------------------------------