session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/telemetry/pricing.mjs

@@ -1,5 +1,5 @@
 /**
- * pricing.mjs — USD price table for token-bucket cost estimation (#1244).
+ * pricing.mjs — USD price table for token-bucket cost estimation (#1244, #1470).
  *
  * The subagent ledger records four token buckets per stop record
  * (`token_input_uncached`, `token_cache_read`, `token_cache_creation`,
@@ -8,23 +8,39 @@
  * an order of magnitude on a cache-heavy run — which is the whole reason this
  * table exists rather than a single `$/token` constant.
  *
- * ## What is measured and what is derived
+ * ## Every rate is a documented figure
  *
- * `input` and `output` are the first-party Anthropic API list prices as
- * published in the bundled model table, sourced on the date `PRICING_TABLE_DATE`
- * carries (2026-09-09) — that constant is the SSOT, never a second date repeated
- * in this prose. `cache_read` and `cache_creation` are DERIVED from the
- * documented ephemeral-cache multipliers (read ≈ 0.1×, 5-minute write ≈ 1.25×
- * the input rate) except where a row carries a documented figure — Claude Fable
- * 5.1 publishes $0.25/MTok cache reads directly, which is NOT 0.1× its $10
- * input rate. Every row therefore declares its own `cache_source` so a reader
- * never has to guess which numbers were read off a price list and which were
- * multiplied out here.
+ * All four rates of every row are first-party Anthropic API list prices, read
+ * off the price page each row names in `source_url` on the date
+ * `PRICING_TABLE_DATE` carries — that constant is the SSOT, never a second date
+ * repeated in this prose. Nothing here is multiplied out. `cache_read` in
+ * particular is never derived from `input`: the ratio is not a constant (Opus
+ * 5.5 reads at 0.05× its input rate, Fable 5.1 at 0.025×, Fable 5 at 0.1×), so
+ * a multiplier would misprice exactly the cache-heavy runs this table exists
+ * for. Each row carries its own provenance fields, so a consumer quoting a
+ * dollar figure can cite where it came from without reading this file.
  *
- * A row with `verified: false` carries a PLACEHOLDER: its numbers are a
- * best-effort stand-in, never a quoted price. `costUsd()` still prices such a
- * row (an estimate is more useful than a null when it is labelled), but any
- * consumer publishing a dollar figure must surface the flag.
+ * `verified: false` would mark a PLACEHOLDER row — a best-effort stand-in,
+ * never a quoted price. No current row carries it; a consumer publishing a
+ * dollar figure must still surface the flag.
+ *
+ * ## Only exact ids resolve
+ *
+ * `priceFor()` accepts an exact table key or an explicit `MODEL_ALIASES` entry
+ * and nothing else. Until #1470 it fell back to the longest table key an id
+ * started with, which handed an unlisted generation the rates of its nearest
+ * neighbour, marked verified.
+ *
+ * ## Series break (#1470, 2026-09-29)
+ *
+ * Session reports written before this fix priced records through that
+ * fallback: `claude-opus-5-5` at `claude-opus-5` rates, `claude-sonnet-5-5` at
+ * `claude-sonnet-5` rates (identical numbers, by coincidence rather than
+ * evidence), and `claude-fable-5` / `claude-opus-4-8` not at all. Nothing
+ * rewrites that history — the metrics ledgers are append-only. Measured
+ * 2026-09-29: 0 of the 9 priced sessions.jsonl reports in this repo contained
+ * such records (the first one reached subagents.jsonl after the last priced
+ * report was written).
  *
  * ## Null means UNKNOWN MODEL, never zero
  *
@@ -39,68 +55,93 @@
  */
 
 /**
- * The date the `input`/`output` rates in PRICING_TABLE were sourced.
- * Any consumer quoting a dollar figure should quote this date beside it — a
- * price without its measurement date ages silently.
+ * The date the rates in PRICING_TABLE were read off the price page. Every row's
+ * `checked_at` equals it. Any consumer quoting a dollar figure should quote this
+ * date beside it — a price without its measurement date ages silently.
  * @type {string}
  */
-export const PRICING_TABLE_DATE = '2026-09-09';
+export const PRICING_TABLE_DATE = '2026-09-29';
 
 /**
  * @typedef {Object} PricingRow
  * @property {number} input           - USD per 1M uncached prompt tokens.
  * @property {number} cache_read      - USD per 1M tokens served from the prompt cache.
- * @property {number} cache_creation  - USD per 1M tokens written to the prompt cache.
+ * @property {number} cache_creation  - USD per 1M tokens written to the prompt cache
+ *   (the `cache_write_ttl` rate).
  * @property {number} output          - USD per 1M completion tokens.
  * @property {boolean} verified       - false ⇒ the row is a labelled placeholder, not a quoted price.
  * @property {'documented'|'derived-multiplier'} cache_source - provenance of the two cache rates.
+ *   Every current row is 'documented'; 'derived-multiplier' is kept for a future row whose cache
+ *   rates are multiplied out and must say so.
+ * @property {string} source_url      - the page all four rates were read from.
+ * @property {string} checked_at      - ISO date the rates were read; equals PRICING_TABLE_DATE.
+ * @property {'anthropic'} provider
+ * @property {'5m'} cache_write_ttl   - which cache-write rate `cache_creation` is.
+ * @property {string} unit            - 'USD per 1M tokens'.
+ * @property {string} surface         - the billing surface and speed the rates apply to.
+ * @property {'standard'} tier        - the service tier the rates apply to.
+ */
+
+/** Provenance shared by every current row — all read off one page on one date. */
+const PROVENANCE = Object.freeze({
+  verified: true,
+  cache_source: 'documented',
+  source_url: 'https://platform.claude.com/docs/en/about-claude/pricing',
+  checked_at: PRICING_TABLE_DATE,
+  provider: 'anthropic',
+  cache_write_ttl: '5m',
+  unit: 'USD per 1M tokens',
+  surface: 'Claude API (first-party), standard speed',
+  tier: 'standard',
+});
+
+/**
+ * One frozen documented row: four USD rates plus the shared provenance. The
+ * rates are spread last, so provenance can never overwrite a price.
+ * @param {{input: number, cache_read: number, cache_creation: number, output: number}} rates
+ * @returns {PricingRow}
  */
+function usd(rates) {
+  return Object.freeze({ ...PROVENANCE, ...rates });
+}
 
 /**
  * Per-model USD-per-million-token rates.
  * @type {Readonly<Record<string, PricingRow>>}
  */
 export const PRICING_TABLE = Object.freeze({
-  // Claude Fable 5.1 — $10 / $50 list; cache reads documented at $0.25/MTok
-  // (NOT the usual 0.1× multiplier), cache writes derived at 1.25× input.
-  'claude-fable-5-1': Object.freeze({
-    input: 10.0,
-    cache_read: 0.25,
-    cache_creation: 12.5,
-    output: 50.0,
-    verified: true,
-    cache_source: 'documented',
-  }),
-  'claude-opus-5': Object.freeze({
-    input: 5.0,
-    cache_read: 0.5,
-    cache_creation: 6.25,
-    output: 25.0,
-    verified: true,
-    cache_source: 'derived-multiplier',
-  }),
-  'claude-sonnet-5': Object.freeze({
-    input: 2.0,
-    cache_read: 0.2,
-    cache_creation: 2.5,
-    output: 10.0,
-    verified: true,
-    cache_source: 'derived-multiplier',
-  }),
-  'claude-haiku-4-5': Object.freeze({
-    input: 1.0,
-    cache_read: 0.1,
-    cache_creation: 1.25,
-    output: 5.0,
-    verified: true,
-    cache_source: 'derived-multiplier',
-  }),
+  // Ceiling: only the 5-minute cache-write rate is priced; a 1-hour write costs 2× input
+  // (Opus 5.5: $8/MTok) and would be under-priced here. Measured 2026-09-29 over 803,788
+  // assistant usage blocks in 10,745 subagent transcripts: `usage.cache_creation
+  // .ephemeral_1h_input_tokens > 0` on 0 blocks. Revisit when the first such block appears.
+  //
+  // Ceiling: list price only — fast mode, `inference_geo: "us"` (1.1×) and batch discounts are
+  // not modelled. Measured 2026-09-29: `usage.speed` = "fast" on 0 of the 374,331 blocks that
+  // carry the field; `inference_geo` = "not_available" on 803,479 and no other value seen.
+  // Revisit when either field shows another value.
+  //
+  // Ceiling: a model absent from this table prices as null, never at a neighbour's rate, so the
+  // rollup reports `total_cost_usd: null` and `cost_records_priced < cost_records_total` — the
+  // intended way missing evidence shows up. That ratio also drops below 1 for records no row can
+  // fix: a token-less record (transcript over the hook's size cap, without usage turns, or
+  // unreadable) and a record with a token-bearing turn that names no model (#1475). Revisit when
+  // an unpriced record names a model id absent from this table: add that model as its own
+  // evidenced row, never as a family prefix or an alias to another generation.
+  'claude-fable-5-1': usd({ input: 10.0, cache_read: 0.25, cache_creation: 12.5, output: 50.0 }),
+  'claude-fable-5': usd({ input: 10.0, cache_read: 1.0, cache_creation: 12.5, output: 50.0 }),
+  'claude-opus-5-5': usd({ input: 4.0, cache_read: 0.2, cache_creation: 5.0, output: 20.0 }),
+  'claude-opus-5': usd({ input: 5.0, cache_read: 0.5, cache_creation: 6.25, output: 25.0 }),
+  'claude-opus-4-8': usd({ input: 5.0, cache_read: 0.5, cache_creation: 6.25, output: 25.0 }),
+  'claude-sonnet-5-5': usd({ input: 2.0, cache_read: 0.2, cache_creation: 2.5, output: 10.0 }),
+  'claude-sonnet-5': usd({ input: 2.0, cache_read: 0.2, cache_creation: 2.5, output: 10.0 }),
+  'claude-haiku-4-5': usd({ input: 1.0, cache_read: 0.1, cache_creation: 1.25, output: 5.0 }),
 });
 
 /**
  * Explicit aliases for model ids that appear in transcripts but are not the
- * canonical table key — dated snapshots and the `[1m]` context-window suffix
- * the harness stamps on long-context sessions.
+ * canonical table key — a dated snapshot of the SAME model and the `[1m]`
+ * context-window suffix the harness stamps on long-context sessions. An alias
+ * never points at another generation.
  * @type {Readonly<Record<string, string>>}
  */
 export const MODEL_ALIASES = Object.freeze({
@@ -113,10 +154,19 @@ export const MODEL_ALIASES = Object.freeze({
 /**
  * Look up the rate row for a model id.
  *
- * Resolution order: exact key → explicit alias → longest matching table key
- * that the id starts with (so `claude-opus-5-20260401` and `claude-opus-5[1m]`
- * both resolve to `claude-opus-5`). Longest-prefix wins so a future
- * `claude-opus-5-1` row is never shadowed by `claude-opus-5`.
+ * Resolution: exact `PRICING_TABLE` key → explicit `MODEL_ALIASES` entry → `null`,
+ * after trimming surrounding whitespace.
+ * Nothing else resolves — no prefix, no pattern, no family fallback — so
+ * `claude-opus-5-20260401`, `claude-opus-5-99` and `claude-haiku-4-5-20251002` are
+ * all UNKNOWN even though each starts with a table key.
+ *
+ * Why no prefix: from the 4.6 generation on, Anthropic ships dateless pinned
+ * model ids (https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions,
+ * retrieved 2026-09-29). The ids that extend a current table key are therefore
+ * other generations, not snapshots of it — `claude-opus-5-5` extends
+ * `claude-opus-5` — and a prefix match priced them at another generation's
+ * rates, marked verified (#1470). A future generation gets its own evidenced
+ * row, never a family prefix.
  *
  * @param {string|null|undefined} modelId
  * @returns {PricingRow|null} the row, or null when the model is UNKNOWN
@@ -129,14 +179,10 @@ export function priceFor(modelId) {
 
   if (Object.hasOwn(PRICING_TABLE, id)) return PRICING_TABLE[id];
 
-  const aliased = MODEL_ALIASES[id];
-  if (aliased && Object.hasOwn(PRICING_TABLE, aliased)) return PRICING_TABLE[aliased];
-
-  let best = null;
-  for (const key of Object.keys(PRICING_TABLE)) {
-    if (id.startsWith(key) && (best === null || key.length > best.length)) best = key;
+  if (Object.hasOwn(MODEL_ALIASES, id) && Object.hasOwn(PRICING_TABLE, MODEL_ALIASES[id])) {
+    return PRICING_TABLE[MODEL_ALIASES[id]];
   }
-  return best === null ? null : PRICING_TABLE[best];
+  return null;
 }
 
 /**
@@ -161,9 +207,10 @@ function num(n) {
 /**
  * Estimate the USD cost of one record's four token buckets.
  *
- * Each bucket is multiplied by ITS OWN rate — a cache read is ~10× cheaper
- * than an uncached prompt token and a cache write ~1.25× more expensive, so a
- * blended rate is not an approximation of this, it is a different number.
+ * Each bucket is multiplied by ITS OWN rate — depending on the row, a cache
+ * read costs a tenth to a fortieth of an uncached prompt token and a 5-minute
+ * cache write 1.25× as much, so a blended rate is not an approximation of
+ * this, it is a different number.
  *
  * @param {object} opts
  * @param {string|null|undefined} opts.model            - model id from the transcript

package/scripts/lib/telemetry/schema.mjs

@@ -93,6 +93,7 @@ export const USAGE_PING_OPTIONAL_FIELDS = Object.freeze([
   'fleet_self_declared',
   'session_record',
   'session_profile',
+  'ledger_complete',
 ]);
 
 /**
@@ -117,6 +118,29 @@ const USAGE_PING_PROJECTED_FIELDS = Object.freeze([...USAGE_PING_FIELDS, ...USAG
  */
 export const SESSION_RECORD_SOURCES = Object.freeze(['ledger', 'derived', 'absent']);
 
+/*
+ * `ledger_complete` — a SECOND, ORTHOGONAL axis beside `session_record`
+ * (GitLab #1416), deliberately NOT a fourth provenance token.
+ *
+ * `deriveSessionFromEvents` (telemetry/sync.mjs) returns a three-state verdict on
+ * the events ledger it read FROM: `true` (every rotation archive present),
+ * `false` (at least one measured gap — a deleted/missing archive), and `null`
+ * (no verdict was produced at all: the read threw, or there was no source). That
+ * verdict decided nothing on the wire, so a derived record reconstructed from a
+ * holey ledger was indistinguishable from one reconstructed from a whole one.
+ *
+ * Why a boolean and not a `derived-partial` token: `SESSION_RECORD_SOURCES` is a
+ * frozen enum mirrored in prose and in the server's `raw_json` consumers, and
+ * completeness is a property of the SOURCE READ, not of WHICH source was used —
+ * widening the provenance enum would make the two facts inseparable and force
+ * every reader of `session_record === 'derived'` to learn a second spelling.
+ *
+ * THE THIRD STATE IS OMISSION: only a real boolean is written. `null` (nothing
+ * measured) omits the key, exactly like `session_profile` — "we did not look" is
+ * never sent as a measured `false`. On the `ledger` branch the field is not set
+ * at ALL: that path never reads the events ledger, so it has no verdict to give.
+ */
+
 /** Exact duration-bucket tokens (ASCII, stable wire values). */
 export const DURATION_BUCKETS = Object.freeze(['<15m', '15-60m', '1-3h', '>3h']);
 
@@ -541,6 +565,7 @@ export function buildUsagePing({
   consentState,
   sessionRecordSource,
   sessionProfile,
+  ledgerComplete,
 } = {}) {
   const session = isPlainObject(sessionRecord) ? sessionRecord : {};
   const invocations = Array.isArray(skillInvocations) ? skillInvocations : [];
@@ -637,6 +662,11 @@ export function buildUsagePing({
     session_record: SESSION_RECORD_SOURCES.includes(sessionRecordSource)
       ? sessionRecordSource
       : 'absent',
+    // ONLY a real boolean travels (#1416). `null`/`undefined` — the read never
+    // happened, or this path never read the events ledger at all — OMITS the
+    // key, the same absent-is-not-empty contract `session_profile` uses above.
+    // Writing `false` there would turn "we did not look" into a measured gap.
+    ...(typeof ledgerComplete === 'boolean' ? { ledger_complete: ledgerComplete } : {}),
     skills: filterRosterNames(skillNames, rosterSkills),
     commands: filterRosterNames(commandNames, rosterCommands),
   };

package/scripts/lib/telemetry/sync.mjs

@@ -41,6 +41,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 { readEventsWithRotations } from '../events.mjs';
 import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { resolvePrivateConfigDir } from '../config/private-config-dir.mjs';
 import { readSessionProfile } from '../state-md.mjs';
@@ -338,12 +339,54 @@ export function readSessionProfileForMetricsDir(metricsDir) {
  * Never throws.
  *
  * @param {string} metricsDir
- * @returns {{ session: object, source: 'derived'|'absent' }}
+ * @returns {{ session: object, source: 'derived'|'absent',
+ *             ledger_complete: boolean|null, ledger_gaps: object[] }}
+ *   `ledger_complete` is `null` — never `false` — when the read produced no
+ *   verdict at all: an undetermined ledger is not a proven gap. TWO paths reach
+ *   that third state (#1423): this function throwing, and the reader finding NO
+ *   source (no active file, no archive, no legacy ring) — in the latter case
+ *   `events: []` is the absence of a ledger, not a measured quiet window.
+ *   `ledger_complete === false` additionally writes ONE stderr line naming the
+ *   gap kinds, because a verdict nothing surfaces is a verdict nobody acts on.
  */
 export function deriveSessionFromEvents(metricsDir) {
   try {
-    const events = readJsonlFile(path.join(metricsDir, 'events.jsonl'), { skipInvalid: true });
-    if (!Array.isArray(events) || events.length === 0) return { session: {}, source: 'absent' };
+    // #1407: read ACROSS rotation boundaries. This reconstruction is the ONLY
+    // source of session facts whenever `sessions.jsonl` has no usable record,
+    // and its sibling window is `DAILY_FLUSH_MS` (24 h) — so a rotation between
+    // a session's start and its flush silently truncated it.
+    //
+    // CEILING (BV-004): the reader loads the active file AND every archive
+    // fully into memory — up to ~60 MB transient at the default
+    // `max-size-mb: 10` / `max-backups: 5`. Measured 2026-09-20 A/B in ONE
+    // process on exactly that worst case (60 MB / 6 sources / 293,994 records,
+    // host loadavg 11.2): median 25.5 ms → 215.8 ms, i.e. +190 ms, which is
+    // 6.4 % of this path's `POST_TIMEOUT_MS` (3000). Acceptable for a
+    // once-per-flush cold read. Revisit if `max-size-mb` is raised past ~100,
+    // if `max-backups` grows, or if the flush budget drops below ~1 s.
+    const ledger = readEventsWithRotations(undefined, {
+      filePath: path.join(metricsDir, 'events.jsonl'),
+    });
+    const events = ledger.events;
+    // A missing archive is a GAP, never an empty window (#1407 AC-3). Carried
+    // on EVERY return below, including the empty ones — that is precisely where
+    // a deleted archive and a quiet period are otherwise indistinguishable.
+    const ledgerVerdict = { ledger_complete: ledger.complete, ledger_gaps: ledger.gaps };
+    // Visibility (#1423): the field had ZERO production consumers — a measured
+    // gap reached nobody. ONE stderr line, at the single point the verdict is
+    // formed, so every return below is covered by construction. Diagnostics on
+    // stderr, never stdout (cli-design.md); no new event, because the gap is a
+    // property of the LEDGER and an event about it would land in the same file.
+    if (ledger.complete === false) {
+      const kinds = [...new Set((ledger.gaps ?? []).map((g) => g?.kind ?? 'unknown'))].sort();
+      process.stderr.write(
+        `⚠ telemetry: events ledger INCOMPLETE — ${ledger.gaps.length} gap(s) ` +
+          `[${kinds.join(', ')}]; the session facts below are reconstructed from a PARTIAL read\n`,
+      );
+    }
+    if (!Array.isArray(events) || events.length === 0) {
+      return { session: {}, source: 'absent', ...ledgerVerdict };
+    }
 
     let startedAt = null;
     let sessionType = null;
@@ -412,7 +455,9 @@ export function deriveSessionFromEvents(metricsDir) {
       profile = undatedShapeProfile;
     }
 
-    if (startedAt === null && sessionType === null && profile === null) return { session: {}, source: 'absent' };
+    if (startedAt === null && sessionType === null && profile === null) {
+      return { session: {}, source: 'absent', ...ledgerVerdict };
+    }
 
     const session = {};
     if (sessionType !== null) session.session_type = sessionType;
@@ -422,9 +467,11 @@ export function deriveSessionFromEvents(metricsDir) {
     // omit-never-fabricate contract session-close-backfill.mjs uses (#914 R1).
     if (lastTs !== null && startedAt !== null && lastTs >= startedAt) session.completed_at = lastTs;
 
-    return { session, source: 'derived' };
+    return { session, source: 'derived', ...ledgerVerdict };
   } catch {
-    return { session: {}, source: 'absent' };
+    // No verdict was ever produced — `null`, not `false`: a measurement that
+    // did not happen is not a measured zero.
+    return { session: {}, source: 'absent', ledger_complete: null, ledger_gaps: [] };
   }
 }
 
@@ -483,6 +530,12 @@ export function buildBatch({
     let sessionForPing;
     /** @type {'ledger'|'derived'|'absent'} */
     let sessionRecordSource = 'ledger';
+    // #1416: the events-ledger completeness verdict, carried to the ping as its
+    // own optional boolean. Stays `null` on the LEDGER branch by construction —
+    // that branch never reads events.jsonl, so it has nothing to report, and
+    // `buildUsagePing` omits the key for anything that is not a real boolean.
+    /** @type {boolean|null} */
+    let ledgerComplete = null;
     if (sessionRecord && typeof sessionRecord.started_at === 'string' && !Number.isNaN(Date.parse(sessionRecord.started_at))) {
       const startMs = Date.parse(sessionRecord.started_at);
       windowInvocations = invocations.filter((rec) => {
@@ -500,6 +553,7 @@ export function buildBatch({
       const derived = deriveSessionFromEvents(dir);
       sessionForPing = derived.session;
       sessionRecordSource = derived.source;
+      ledgerComplete = derived.ledger_complete;
 
       const derivedStartMs = Date.parse(sessionForPing.started_at);
       const cutoff = (Number.isNaN(Date.parse(nowIso)) ? Date.now() : Date.parse(nowIso)) - DAILY_FLUSH_MS;
@@ -522,6 +576,7 @@ export function buildBatch({
       consentState,
       sessionRecordSource,
       sessionProfile: readSessionProfileForMetricsDir(dir),
+      ledgerComplete,
     });
 
     const target = statePath || TELEMETRY_JSON_PATH;

package/scripts/lib/telemetry-flush-health-banner.mjs

@@ -31,9 +31,11 @@
  * @module scripts/lib/telemetry-flush-health-banner
  */
 
-import { existsSync, openSync, readSync, fstatSync, closeSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
+import { readTailWindow } from './tail-window.mjs';
+
 /**
  * Bytes of `events.jsonl` read from the END of the file.
  *
@@ -82,31 +84,11 @@ function sanitizeReason(reason) {
  * @returns {{text: string} | {missing: true} | {error: string}}
  */
 function readTail(file) {
-  let fd;
   try {
-    fd = openSync(file, 'r');
-    const { size } = fstatSync(fd);
-    const length = Math.min(size, TAIL_BYTES);
-    const start = size - length;
-    const buf = Buffer.allocUnsafe(length);
-    let read = 0;
-    while (read < length) {
-      const n = readSync(fd, buf, read, length - read, start + read);
-      if (n <= 0) break;
-      read += n;
-    }
-    return { text: buf.subarray(0, read).toString('utf8') };
+    return { text: readTailWindow(file, TAIL_BYTES).text };
   } catch (err) {
     if (err?.code === 'ENOENT') return { missing: true };
     return { error: typeof err?.code === 'string' ? err.code : 'EUNKNOWN' };
-  } finally {
-    if (fd !== undefined) {
-      try {
-        closeSync(fd);
-      } catch {
-        /* best effort */
-      }
-    }
   }
 }
 

package/scripts/lib/test-runner/issue-reconcile.mjs

@@ -22,10 +22,17 @@
  *   triageDecision(finding, candidates)
  *     → {action: 'create'|'update'|'ignore', target?, reason: string, confidence: number}
  *
+ *   buildIssueBody(finding, fp) → string
+ *
+ *   neutralizeFingerprintSentinel(text) → string
+ *   fingerprintSentinelLine(fp) → string
+ *     The one shared sentinel writer + neutraliser, also used by
+ *     ux-grill/reconcile.mjs (#1339 P6).
+ *
  *   ReconcileError
  *
  * Security:
- *   - #388 (SEC-IR-MED-1): sentinel injection hardening — sanitizeRecommendation()
+ *   - #388 (SEC-IR-MED-1): sentinel injection hardening — neutralizeFingerprintSentinel()
  *     strips **Fingerprint:** literals from free-text fields before they are
  *     embedded in the body (before the authoritative sentinel line is appended).
  *   - #389 (SEC-IR-LOW-1): maxBuffer set to 4 MB on every execFile call;
@@ -126,39 +133,64 @@ function validateFinding(finding) {
 // ---------------------------------------------------------------------------
 
 /**
- * Sanitize free-text recommendation fields before embedding in the issue body.
- * Replaces any literal `**Fingerprint:**` with `__Fingerprint__` to prevent
- * a crafted recommendation from spoofing the authoritative fingerprint sentinel
- * line that is appended by buildIssueBody().
+ * Neutralise every `**Fingerprint:**` literal in untrusted text by rewriting it
+ * to `__Fingerprint__`. The ONE copy of this neutralisation: this module's
+ * {@link buildIssueBody} and `ux-grill/reconcile.mjs` both route free text
+ * through it (#1339 P6), so a hardening added here reaches both producers.
  *
- * Context: glab parses issue bodies as Markdown. If `recommendation` contained
+ * Context: glab parses issue bodies as Markdown. If a free-text field contained
  * `**Fingerprint:** <attacker-hash>`, a grep for the fingerprint sentinel in
  * listExistingFindings() would match the spoofed value instead of the real one,
  * bypassing dedup. Replacing the literal prevents the attack without altering
- * the semantic meaning of the recommendation text.
+ * the semantic meaning of the text.
+ *
+ * @param {unknown} text - coerced with `String(text ?? '')`
+ * @returns {string}
+ */
+export function neutralizeFingerprintSentinel(text) {
+  // gi flag: case-insensitive match so **fingerprint:** and **FINGERPRINT:** variants
+  // are also neutralized. Sanitizer is intentionally broader than the case-sensitive
+  // extractor regex — this is the correct asymmetry (#388 SEC-IR-MED-1).
+  return String(text ?? '').replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
+}
+
+/**
+ * The authoritative dedup sentinel line, in the exact shape
+ * {@link extractFingerprintFromBody} reads. The caller passes an
+ * already-trusted value; this function does not sanitise it.
+ *
+ * @param {string} fp - 16-char hex fingerprint
+ * @returns {string}
+ */
+export function fingerprintSentinelLine(fp) {
+  return `**Fingerprint:** \`${fp}\``;
+}
+
+/**
+ * Sanitize free-text recommendation fields before embedding in the issue body
+ * (#388 SEC-IR-MED-1) — {@link neutralizeFingerprintSentinel} for a non-empty
+ * string, anything else returned unchanged (a `null` description is dropped by
+ * buildIssueBody's line filter rather than rendered as an empty line).
  *
  * @param {string|undefined|null} text
  * @returns {string|undefined|null}
  */
 function sanitizeRecommendation(text) {
   if (!text || typeof text !== 'string') return text;
-  // gi flag: case-insensitive match so **fingerprint:** and **FINGERPRINT:** variants
-  // are also neutralized. Sanitizer is intentionally broader than the case-sensitive
-  // extractor regex — this is the correct asymmetry (#388 SEC-IR-MED-1).
-  return text.replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
+  return neutralizeFingerprintSentinel(text);
 }
 
 /**
  * Render untrusted text as the content of ONE inline Markdown code span:
- * sentinel literals neutralised (sanitizeRecommendation), line breaks and NUL
- * folded to a space, backticks turned into `'` — so a page-controlled locator
- * can neither close its code span nor start a new body line.
+ * sentinel literals neutralised, line breaks and NUL folded to a space,
+ * backticks turned into `'` — so a page-controlled locator can neither close
+ * its code span nor start a new body line.
  *
  * @param {unknown} text
  * @returns {string}
  */
 function codeSpanContent(text) {
-  return sanitizeRecommendation(String(text ?? ''))
+  return neutralizeFingerprintSentinel(text)
     .replace(/[\r\n\0]+/g, ' ')
     .replace(/`/g, "'");
 }
@@ -218,7 +250,7 @@ export function buildIssueBody(finding, fp) {
     '',
     safeRecommendation ? `**Recommendation:** ${safeRecommendation}` : null,
     '',
-    `**Fingerprint:** \`${fp}\``,
+    fingerprintSentinelLine(fp),
     `**Severity:** ${finding.severity}`,
     `**Check:** ${finding.checkId}`,
     `**Locator:** \`${codeSpanContent(finding.locator)}\``,