session-orchestrator 3.17.0 → 3.19.0

package/scripts/lib/validate/check-unicode-safety.mjs

@@ -187,6 +187,7 @@ const ALLOWED_EMOJI_CODEPOINTS = new Set([
   0x2139, //  ℹ
   0x2194, //  ↔
   0x26a0, //  ⚠
+  0x26d4, //  ⛔ (deny headline in emitDeny's operator systemMessage — #906)
   0x2705, //  ✅
   0x274c, //  ❌
   0x2b50, //  ⭐

package/scripts/lib/validate-vendored-rules.mjs

@@ -277,9 +277,17 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
       violations.push({
         rule: 'paths-frontmatter',
         severity: 'error',
+        // NOTE (#795 / corrected 2026-07-25): the previous wording claimed rule-loader.mjs
+        // does not recognize `paths:` and that such a rule loads always-on. Both are false
+        // since #795 — `rule-loader.mjs:275` accepts `paths` alongside `globs`, and `:313`
+        // treats it as a fallback alias (`globs:` wins silently when both are present), so a
+        // `paths:`-only rule IS glob-scoped. The probe itself stays: it enforces the canonical
+        // vendoring form, which is a convention gate, not a loader-compatibility gate. That
+        // intent survives #795 and is the subject of the #742 fleet canonicalisation sweep.
         message:
-          `${relPath}: frontmatter declares a top-level 'paths:' key, which rule-loader.mjs does not recognize — ` +
-          `it is silently ignored and the rule loads as always-on instead of glob-scoped. Migrate to 'globs:'.`,
+          `${relPath}: frontmatter declares a top-level 'paths:' key. It is a recognized alias ` +
+          `for 'globs:' (issue #795), so the rule does load glob-scoped — but 'globs:' is the ` +
+          `canonical form for vendored rules. Migrate to 'globs:' (see issue #742).`,
         line: lineWithinFrontmatter(fm.startLine, fm.body, pathsMatch.index),
       });
     }

package/scripts/lib/vault-archive.mjs

@@ -240,8 +240,23 @@ export function buildArchiveFields({
   const finalType = VAULT_TYPE_ENUM.includes(base.type) ? base.type : type;
 
   // created: keep a valid existing date (original creation), else today.
-  const created =
-    typeof base.created === 'string' && ISO_DATE_RE.test(base.created) ? base.created : dateStr;
+  //
+  // js-yaml's default schema auto-resolves an unquoted ISO-8601-shaped scalar
+  // (the canonical `created: 2026-01-01` form) into a native `Date`, NOT a
+  // string — same quirk as moc-staleness-banner.mjs's `_readMocStalenessDays`
+  // (verified: `YAML.load('created: 2026-01-01').created instanceof Date`).
+  // Without this branch, an unquoted existing `created:` silently fails the
+  // `typeof === 'string'` check below and gets clobbered with today's date
+  // (#837). Accept both shapes; anything else (missing, number, array, an
+  // invalid Date, …) falls back to `dateStr` as before.
+  let created;
+  if (typeof base.created === 'string' && ISO_DATE_RE.test(base.created)) {
+    created = base.created;
+  } else if (base.created instanceof Date && !Number.isNaN(base.created.getTime())) {
+    created = base.created.toISOString().slice(0, 10);
+  } else {
+    created = dateStr;
+  }
 
   // title: explicit arg wins, else existing, else undefined (caller may derive).
   let finalTitle = title;

package/scripts/lib/vault-backfill/glab.mjs

@@ -36,6 +36,14 @@ export function assertGlabExists(dieFn) {
 
 /**
  * Run a glab command, return { ok, stdout, stderr }.
+ *
+ * Host-pinning (#872): deliberately ambient — this module runs instance-wide
+ * queries (e.g. `glab repo list -g <group>`) that are not scoped to a single
+ * repo/project, so there is no single `-R`/`--repo` spec to pin. If a
+ * caller ever needs single-repo host-pinning here, use `--hostname` (the
+ * flag `glab api` and instance-wide subcommands accept), NOT `-R`/`--repo` —
+ * see `scripts/lib/vcs-repo-spec.mjs` for the `resolveRepoSpec` (`-R`) vs
+ * `resolveRepoHost` (`--hostname`) contract this repo already established.
  */
 export function glabRun(glabArgs) {
   vlog(`glab ${glabArgs.join(' ')}`);

package/scripts/lib/vault-mirror/process.mjs

@@ -10,6 +10,7 @@ import { join, resolve, basename } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { subjectToSlug, isValidSlug, uuidPrefix8, toDate, parseFrontmatter } from './utils.mjs';
+import { isRealSession } from '../session-schema/filters.mjs';
 import { resolveRepoNamespace } from './namespace.mjs';
 import { detectLearningSchema, normalizeLearningEntry, generateLearningNote, generateLearningNoteV2 } from './render-learnings.mjs';
 import { detectSessionSchema, normalizeSessionEntry, generateSessionNote, generateSessionNoteV2, generateSessionNoteV3 } from './render-sessions.mjs';
@@ -464,6 +465,35 @@ export async function processSession(rawEntry, _lineNum, ctx) {
     session_id = session_id.slice(0, 240).replace(/-+$/, '');
   }
 
+  // #909 ABANDONED FILTER: a phantom stub backfilled from events.jsonl for a
+  // session that never ran /close is legitimate DATA in the ledger but not
+  // legitimate SIGNAL in a knowledge store — it records that a start happened,
+  // with 0 waves, 0 agents and synthesized fields. Mirroring it would add a note
+  // whose every number is a placeholder.
+  //
+  // The predicate is `isRealSession` from scripts/lib/session-schema/filters.mjs
+  // (fail-open: only an explicit `status: 'abandoned'` is filtered; the absent-
+  // status pre-#724 majority passes through). Reused rather than re-implemented
+  // so the ledger's definition of "real" lives in exactly one place.
+  //
+  // Placed BEFORE repoNs resolution and BEFORE the quality-gate render: skipping
+  // early avoids a git subprocess and a wasted render for a record we discard.
+  // This is deliberately REDUNDANT with the renderer's status mapping (#909,
+  // render-sessions.mjs) — see that module's header. The filter removes one
+  // status from the vault; the mapping keeps every OTHER status honest, and
+  // guards the generators' other entry point (the render.mjs barrel).
+  if (!isRealSession(entry)) {
+    emitAction({
+      action: 'skipped-abandoned',
+      path: null,
+      kind,
+      id: session_id,
+      vaultDir,
+      meta: { reason: `status:${entry?.status}` },
+    });
+    return;
+  }
+
   // #732: resolve the leak-guarded repo namespace ONCE per session, BEFORE the
   // quality gate, so both the write path (targetDir, below) AND the rendered
   // frontmatter (`source-repo`) use the SAME sanitised / pseudonym-mapped value.

package/scripts/lib/vault-mirror/render-sessions.mjs

@@ -18,6 +18,216 @@ import { toDate, buildTag, slugifyIdSafe } from './utils.mjs';
 
 const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
 
+/**
+ * Placeholders for an ABSENT optional field (session-reviewer M1).
+ *
+ * These are the tokens the v2/v3 generators already use — `'?'` inside a wave
+ * table cell (generateSessionNoteV2's wave rows), `'n/a'` in a prose bullet
+ * (both v2 and v3). The v1 generator predates both guards and interpolated the
+ * same optional fields raw, so any record lacking one wrote the literal string
+ * `undefined` into a vault note a human reads.
+ *
+ * ── ABSENT IS NOT ZERO ─────────────────────────────────────────────────────
+ *
+ * Every use site must apply these with `??`, NEVER `||`. A wave that genuinely
+ * changed 0 files, or dispatched 0 agents, has a MEASURED zero and must render
+ * `0`; only a field the producer never wrote is unknown. `||` collapses that
+ * distinction (`0 || '?'` → `'?'`, asserting "unknown" about a real
+ * measurement); `??` preserves it (`0 ?? '?'` → `0`).
+ */
+const MISSING_CELL = '?';
+const MISSING_VALUE = 'n/a';
+
+/**
+ * Render the `**Duration:**` bullet value for all three generators (#969 LOW-1).
+ *
+ * All three sites used to read `Math.round((duration_seconds ?? 0) / 60)`, three
+ * lines that violated the banner directly above them: neither `duration_minutes`
+ * nor `duration_seconds` is in ANY of the `RENDERABLE_SESSION_FIELDS_*` lists,
+ * so absence is reachable, and a record lacking both rendered `Duration: 0m` —
+ * a claimed MEASURED zero, contradicted on the same line by its own
+ * `started_at → completed_at` span, and sitting beside correctly-rendered `n/a`s.
+ * "0m" reads as a verified fact; that is the more damaging direction.
+ *
+ * The whole chain is `??`, never `||`, so a genuinely measured zero survives:
+ * `duration_minutes: 0` renders `0m`, and so does `duration_seconds: 0`
+ * (`Math.round(0 / 60)` is `0`, and `0 ?? x` is `0`). Only a field the producer
+ * never wrote becomes `MISSING_VALUE`. The suffix is applied HERE rather than at
+ * the call sites, because `${MISSING_VALUE}m` would render `n/am`.
+ *
+ * @param {unknown} durationSeconds — v1/v2/v3 `duration_seconds`.
+ * @param {unknown} [durationMinutes] — v3 `duration_minutes`; WINS when both are
+ *   present, preserving v3's original precedence.
+ * @returns {string} e.g. `'42m'`, `'0m'`, or `'n/a'`.
+ */
+function renderDuration(durationSeconds, durationMinutes) {
+  const fromSeconds =
+    durationSeconds === undefined || durationSeconds === null
+      ? undefined
+      : Math.round(durationSeconds / 60);
+  const minutes = durationMinutes ?? fromSeconds;
+  return minutes === undefined || minutes === null ? MISSING_VALUE : `${minutes}m`;
+}
+
+/**
+ * ── RENDERABLE ⊋ SCHEMA-VALID (#964) ───────────────────────────────────────
+ *
+ * Each generator gates on its own required-field list. Before #964 all three
+ * lists were function-local `const`s with no stated relationship to
+ * `REQUIRED_FIELDS` (scripts/lib/session-schema/constants.mjs) — the write-path
+ * schema — which made five independent notions of "a valid session record" in
+ * one codebase, drifting silently. They are lifted here, exported, and pinned
+ * against `REQUIRED_FIELDS` by a mechanical superset test in
+ * tests/lib/vault-mirror/render-sessions.test.mjs.
+ *
+ * The relationship is deliberately asymmetric, not a duplicate:
+ *
+ *   `REQUIRED_FIELDS`  — "this record is well-formed". The writer
+ *     (scripts/emit-session.mjs) REFUSES a record that fails it.
+ *   these lists        — "this record renders into a note a human can read".
+ *     vault-mirror SKIPS a record that fails them; the record stays valid.
+ *
+ * Collapsing the two would destroy that distinction. Hence `effectiveness`:
+ * optional to the writer (a record lacking it is fine), required by the v1
+ * renderer (a note reading `planned=n/a, completed=n/a, carryover=n/a,
+ * rate=n/a` is worse than no note — indistinguishable from a real session whose
+ * metrics happened to be absent).
+ *
+ * The predicate here is VALUE presence (`null`/`undefined` both fail); the
+ * validator's is KEY presence. See `_validateRequiredFields` for why.
+ */
+
+/**
+ * v1 — the only generator reachable from a write-path-valid record (measured:
+ * 205/205 live ledger records at HEAD 730ee9d route v1). Its list is
+ * `REQUIRED_FIELDS` plus `effectiveness`, i.e. a strict superset.
+ */
+export const RENDERABLE_SESSION_FIELDS_V1 = Object.freeze([
+  'session_id',
+  'session_type',
+  'started_at',
+  'completed_at',
+  'total_waves',
+  'total_agents',
+  'total_files_changed',
+  'agent_summary',
+  'waves',
+  'effectiveness',
+]);
+
+/**
+ * v2 — legacy S69+ producer shape. Requires FEWER fields than `REQUIRED_FIELDS`
+ * (no `total_waves`/`total_agents`/`total_files_changed`/`agent_summary`)
+ * because it DERIVES every one of them from the wave array, and carries the
+ * file count as top-level `files_changed` — the alias `SESSION_KEY_ALIASES`
+ * maps to `total_files_changed` on read.
+ *
+ * That shortfall is an EARNED carve-out from the superset rule, not an
+ * oversight: `detectSessionSchema` routes to v2 only when
+ * `total_agents === undefined`, and `validateSession` rejects exactly that
+ * (missing key, or present-but-not-a-number). No record can satisfy both. The
+ * test asserts the disjointness rather than trusting this comment.
+ */
+export const RENDERABLE_SESSION_FIELDS_V2 = Object.freeze([
+  'session_id',
+  'session_type',
+  'started_at',
+  'completed_at',
+  'waves',
+  'files_changed',
+  'effectiveness',
+]);
+
+/**
+ * v3 — coordinator-direct shape with SCALAR `waves`. Same earned carve-out as
+ * v2, from a sharper contradiction: `_validateWaves` throws unless
+ * `Array.isArray(entry.waves)`, `generateSessionNoteV3` throws unless
+ * `typeof entry.waves === 'number'`. A value cannot be both, so no record can
+ * satisfy both contracts — v3 is unreachable from the sanctioned writer by
+ * construction, and measurement agrees (0/205).
+ */
+export const RENDERABLE_SESSION_FIELDS_V3 = Object.freeze([
+  'session_id',
+  'session_type',
+  'started_at',
+  'completed_at',
+  'waves',
+  'effectiveness',
+]);
+
+/**
+ * Session-ledger status → vault-frontmatter status mapping (#909).
+ *
+ * ── WHY A MAPPING AND NOT A PASS-THROUGH ───────────────────────────────────
+ *
+ * The two value ranges are DISJOINT:
+ *
+ *   `sessions.jsonl` `status` — `completed` | `abandoned`, or absent/null on
+ *     every pre-#724 record (SESSION_STATUS, scripts/lib/session-schema/validator.mjs).
+ *   vault frontmatter `status` — `draft` | `active` | `verified` | `archived` |
+ *     `production` | `mvp` | `idea` (vaultNoteStatusSchema, skills/vault-sync/validator.mjs).
+ *
+ * Neither `completed` nor `abandoned` is a legal vault status. Emitting
+ * `session.status` verbatim would therefore write an off-schema frontmatter
+ * value and hard-fail `vault-sync`, which runs as a session-end Phase 1 gate.
+ *
+ * ── WHAT THIS REPLACES ─────────────────────────────────────────────────────
+ *
+ * All three generators previously hard-coded `status: verified` (frontmatter
+ * line + `status/verified` tag) and never read `session.status` at all — so
+ * every mirrored session claimed "verified" regardless of how it ended. A false
+ * `verified` in a knowledge store is worse than a missing note: it is a claim
+ * downstream readers cannot distinguish from a true one.
+ *
+ * ── THE MAPPING ────────────────────────────────────────────────────────────
+ *
+ *   completed    → verified   (closed through the full /close flow incl. gates)
+ *   abandoned    → draft      (phantom stub synthesized by the SessionEnd
+ *                              backfill from events.jsonl; incomplete fields,
+ *                              never gate-verified — `draft` is the honest
+ *                              "unfinished" value)
+ *   absent/null  → verified   (pre-#724 records predate the field; per
+ *                              filters.mjs's fail-open contract these are
+ *                              genuine sessions, and this keeps the 200+
+ *                              already-mirrored notes byte-identical → no
+ *                              re-write churn on the next mirror run)
+ *   anything else→ draft      (fail-safe: the ledger enum is additive-optional
+ *                              and has grown once already; an unmapped future
+ *                              value must never be able to emit an off-schema
+ *                              vault status, and must never silently claim
+ *                              `verified`)
+ */
+const VAULT_STATUS_BY_SESSION_STATUS = Object.freeze({
+  completed: 'verified',
+  abandoned: 'draft',
+});
+
+/** Vault status for a record that carries no `status` field (pre-#724). */
+const VAULT_STATUS_WHEN_ABSENT = 'verified';
+
+/** Vault status for a ledger value outside the known enum (fail-safe). */
+const VAULT_STATUS_FALLBACK = 'draft';
+
+/**
+ * Resolve the vault-frontmatter `status` for a session record.
+ *
+ * Guaranteed to return a member of vaultNoteStatusSchema for ANY input —
+ * including `null`, a non-object, or a hostile string such as `'constructor'`
+ * (hence `Object.hasOwn` rather than a bare property read, which would return
+ * an inherited `Object.prototype` member).
+ *
+ * @param {unknown} entry — a parsed sessions.jsonl record
+ * @returns {'verified'|'draft'}
+ */
+export function vaultStatusForSession(entry) {
+  if (entry === null || typeof entry !== 'object') return VAULT_STATUS_WHEN_ABSENT;
+  const raw = entry.status;
+  if (raw === null || raw === undefined || raw === '') return VAULT_STATUS_WHEN_ABSENT;
+  return Object.hasOwn(VAULT_STATUS_BY_SESSION_STATUS, raw)
+    ? VAULT_STATUS_BY_SESSION_STATUS[raw]
+    : VAULT_STATUS_FALLBACK;
+}
+
 /**
  * Frontmatter line emitter — skips emission when value is null/undefined/empty
  * to avoid template-literal coercion bugs (e.g. `platform: undefined` → "undefined").
@@ -34,11 +244,21 @@ function fmLine(key, value) {
  *   v2 (S69+):    files_changed (top-level), waves[{agents, agents_done, agents_partial, agents_failed, dispatch, duration_s}]
  *   v3 (2026-05+): coordinator-direct records — `waves` is a SCALAR count and
  *                  `agents_dispatched` is a scalar; no per-wave array breakdown.
- *                  This is the shape session-end actually emits (#491), which
- *                  previously fell through to v1 validation and was rejected as
- *                  `skipped-invalid` (no vault session-note was ever written).
+ *                  Added for #491, when such records fell through to v1
+ *                  validation and were rejected as `skipped-invalid`.
  * v1 and v2 both carry `waves` as an ARRAY, so a numeric `waves` is the
  * unambiguous v3 discriminator.
+ *
+ * #964 — CORRECTION. This comment previously claimed v3 was "the shape
+ * session-end actually emits". It is not, and cannot be: `validateSession`
+ * requires `Array.isArray(waves)`, so a scalar-`waves` record is refused by
+ * `scripts/emit-session.mjs` before it can be written. Census over the live
+ * ledger at HEAD 730ee9d — 205 parseable records, post-`normalizeSessionEntry`:
+ * **v1 205, v2 0, v3 0**. Both v2 and v3 are read-path tolerances for foreign /
+ * legacy producer shapes, not targets of the sanctioned writer. v3's live
+ * reachability is therefore zero; see the follow-up note in the #964 report
+ * before treating it as dead code — deletion is a separate decision, and the
+ * `normalizeSessionEntry` alias path can still synthesize a scalar `waves`.
  */
 export function detectSessionSchema(entry) {
   if (!entry) return 'v1';
@@ -80,8 +300,7 @@ export function normalizeSessionEntry(entry) {
 }
 
 export function generateSessionNote(entry, options = {}) {
-  const REQUIRED_SESSION_FIELDS = ['session_id', 'session_type', 'started_at', 'completed_at', 'total_waves', 'total_agents', 'total_files_changed', 'agent_summary', 'waves', 'effectiveness'];
-  for (const field of REQUIRED_SESSION_FIELDS) {
+  for (const field of RENDERABLE_SESSION_FIELDS_V1) {
     if (entry[field] === null || entry[field] === undefined) {
       throw new Error(`vault-mirror: session entry missing required field '${field}' (session_id=${entry.session_id ?? '<no session_id>'})`);
     }
@@ -114,9 +333,19 @@ export function generateSessionNote(entry, options = {}) {
 
   const created = toDate(started_at);
   const updated = toDate(completed_at);
-  const durationMin = Math.round((duration_seconds ?? 0) / 60);
-  const { planned_issues, completed, carryover, emergent, completion_rate } = effectiveness;
-  const ratePercent = Math.round(completion_rate * 100) + '%';
+  const durationLabel = renderDuration(duration_seconds);
+  // #M1: every `effectiveness` sub-field is OPTIONAL (validator.mjs
+  // `_validateOptionalFields` shape-checks the object, never its members), so a
+  // raw interpolation writes the literal string `undefined` into a note a human
+  // reads. `??` (never `||`) is load-bearing: a measured `0` must survive as `0`,
+  // only a genuinely absent value becomes the placeholder. The alias reads are
+  // ordered v1-field-first so a record that rendered a value before renders the
+  // exact same value now — this change can only ever replace `undefined`/`NaN`.
+  const { planned_issues, carryover, completion_rate } = effectiveness;
+  const completed = effectiveness.completed ?? effectiveness.completed_issues ?? MISSING_VALUE;
+  const emergent = effectiveness.emergent ?? effectiveness.unplanned_finds ?? MISSING_VALUE;
+  const ratePercent =
+    typeof completion_rate === 'number' ? Math.round(completion_rate * 100) + '%' : MISSING_VALUE;
   const { complete, partial, failed, spiral } = agent_summary;
 
   const titleValue = `Session ${created} — ${session_type}`;
@@ -128,13 +357,21 @@ export function generateSessionNote(entry, options = {}) {
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
   const noteId = slugifyIdSafe(session_id) ?? session_id;
-  const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', 'verified'])}]`;
-
-  // Build wave table rows
+  // #909: the real ledger status, mapped into the vault enum — never hard-coded.
+  const vaultStatus = vaultStatusForSession(entry);
+  const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
+
+  // Build wave table rows.
+  //
+  // #M1: only `wave` and `role` are schema-REQUIRED per wave (validator.mjs
+  // `_validateWaves`); `agent_count`, `files_changed` and `quality` are never
+  // validated, so all three are optional and were rendering as the literal
+  // string `undefined`. Guarded with the same `?? '?'` the v2 generator's wave
+  // rows already used — `??` so a measured `0` still renders `0`.
   const waveRows = waves
     .map(
       (w) =>
-        `| ${w.wave} | ${w.role} | ${w.agent_count} | ${w.files_changed} | ${w.quality} |`,
+        `| ${w.wave} | ${w.role} | ${w.agent_count ?? MISSING_CELL} | ${w.files_changed ?? MISSING_CELL} | ${w.quality ?? MISSING_CELL} |`,
     )
     .join('\n');
 
@@ -152,7 +389,7 @@ export function generateSessionNote(entry, options = {}) {
 id: ${noteId}
 type: session
 title: ${title}
-status: verified
+status: ${vaultStatus}
 created: ${created}
 updated: ${updated}
 tags: ${tags}
@@ -162,9 +399,9 @@ ${fmLine('source-repo', repoNs)}_generator: ${GENERATOR_MARKER}
 # Session ${session_id}
 
 - **Type:** ${session_type}${platformBullet}
-- **Duration:** ${durationMin}m (${started_at} → ${completed_at})
+- **Duration:** ${durationLabel} (${started_at} → ${completed_at})
 - **Waves:** ${total_waves} · **Agents:** ${total_agents} · **Files changed:** ${total_files_changed}
-- **Effectiveness:** planned=${planned_issues}, completed=${completed}, carryover=${carryover}, emergent=${emergent}, rate=${ratePercent}
+- **Effectiveness:** planned=${planned_issues ?? MISSING_VALUE}, completed=${completed}, carryover=${carryover ?? MISSING_VALUE}, emergent=${emergent}, rate=${ratePercent}
 
 ## Wave breakdown
 
@@ -179,8 +416,7 @@ ${waveRows}
 }
 
 export function generateSessionNoteV2(entry, options = {}) {
-  const REQUIRED_SESSION_V2_FIELDS = ['session_id', 'session_type', 'started_at', 'completed_at', 'waves', 'files_changed', 'effectiveness'];
-  for (const field of REQUIRED_SESSION_V2_FIELDS) {
+  for (const field of RENDERABLE_SESSION_FIELDS_V2) {
     if (entry[field] === null || entry[field] === undefined) {
       throw new Error(`vault-mirror: session entry missing required field '${field}' (session_id=${entry.session_id ?? '<no session_id>'})`);
     }
@@ -196,7 +432,7 @@ export function generateSessionNoteV2(entry, options = {}) {
 
   const created = toDate(started_at);
   const updated = toDate(completed_at);
-  const durationMin = Math.round((duration_seconds ?? 0) / 60);
+  const durationLabel = renderDuration(duration_seconds);
 
   // Derive v1-equivalent aggregates from v2 wave structure
   const totalWaves = waves.length;
@@ -217,7 +453,9 @@ export function generateSessionNoteV2(entry, options = {}) {
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
   const noteId = slugifyIdSafe(session_id) ?? session_id;
-  const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', 'verified'])}]`;
+  // #909: the real ledger status, mapped into the vault enum — never hard-coded.
+  const vaultStatus = vaultStatusForSession(entry);
+  const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
 
   const waveRows = waves
     .map((w) => `| ${w.wave} | ${w.role} | ${w.agents ?? '?'} | ${w.dispatch ?? '?'} | ${w.duration_s ?? '?'}s | ${w.agents_done ?? 0}/${w.agents_partial ?? 0}/${w.agents_failed ?? 0} |`)
@@ -236,7 +474,7 @@ export function generateSessionNoteV2(entry, options = {}) {
 id: ${noteId}
 type: session
 title: ${title}
-status: verified
+status: ${vaultStatus}
 created: ${created}
 updated: ${updated}
 tags: ${tags}
@@ -246,7 +484,7 @@ ${fmLine('source-repo', repoNs)}_generator: ${GENERATOR_MARKER}
 # Session ${session_id}
 
 - **Type:** ${session_type}${branchLine}
-- **Duration:** ${durationMin}m (${started_at} → ${completed_at})
+- **Duration:** ${durationLabel} (${started_at} → ${completed_at})
 - **Waves:** ${totalWaves} · **Agents:** ${totalAgents} · **Files changed:** ${files_changed}
 - **Effectiveness:** planned=${planned_issues ?? 'n/a'}, carryover=${carryover}, rate=${ratePercent}
 - **Issues closed:** ${closedList}
@@ -274,8 +512,7 @@ ${notesBlock}`;
  * and reject this shape, so it gets its own renderer.
  */
 export function generateSessionNoteV3(entry, options = {}) {
-  const REQUIRED_SESSION_V3_FIELDS = ['session_id', 'session_type', 'started_at', 'completed_at', 'waves', 'effectiveness'];
-  for (const field of REQUIRED_SESSION_V3_FIELDS) {
+  for (const field of RENDERABLE_SESSION_FIELDS_V3) {
     if (entry[field] === null || entry[field] === undefined) {
       throw new Error(`vault-mirror: session entry missing required field '${field}' (session_id=${entry.session_id ?? '<no session_id>'})`);
     }
@@ -296,24 +533,42 @@ export function generateSessionNoteV3(entry, options = {}) {
 
   const created = toDate(started_at);
   const updated = toDate(completed_at);
-  const durationMin = duration_minutes ?? Math.round((duration_seconds ?? 0) / 60);
-
+  const durationLabel = renderDuration(duration_seconds, duration_minutes);
+
+  // #968 — ABSENT IS NOT ZERO. Two sites here defaulted an absent value to `0`,
+  // claiming a measured zero the producer never wrote: `emergent` (`?? 0`) and
+  // the `agent_summary` destructuring defaults (`= 0`, over an `as` that itself
+  // falls back to `{}`). That was inconsistent with v3's OWN treatment of the
+  // neighbouring fields — `carryover` used `?? 'n/a'` one line above `emergent`'s
+  // `?? 0` — and it is the more damaging direction: "0 agents failed" reads as a
+  // verified fact, "n/a" reads as unknown. `??` (never `||`) is load-bearing at
+  // every site: a MEASURED 0 must still render `0`.
   const completionRate = effectiveness.completion_rate;
-  const ratePercent = typeof completionRate === 'number' ? Math.round(completionRate * 100) + '%' : 'n/a';
-  const completed = effectiveness.completed_issues ?? effectiveness.completed ?? 'n/a';
-  const carryover = effectiveness.carryover ?? 'n/a';
-  const emergent = effectiveness.unplanned_finds ?? effectiveness.emergent ?? 0;
+  const ratePercent =
+    typeof completionRate === 'number' ? Math.round(completionRate * 100) + '%' : MISSING_VALUE;
+  const completed = effectiveness.completed_issues ?? effectiveness.completed ?? MISSING_VALUE;
+  const carryover = effectiveness.carryover ?? MISSING_VALUE;
+  const emergent = effectiveness.unplanned_finds ?? effectiveness.emergent ?? MISSING_VALUE;
 
-  const agentsValue = typeof agents_dispatched === 'number' ? agents_dispatched : 'n/a';
+  const agentsValue = typeof agents_dispatched === 'number' ? agents_dispatched : MISSING_VALUE;
   const as = agent_summary && typeof agent_summary === 'object' ? agent_summary : {};
-  const { complete = 0, partial = 0, failed = 0, spiral = 0 } = as;
+  const complete = as.complete ?? MISSING_VALUE;
+  const partial = as.partial ?? MISSING_VALUE;
+  const failed = as.failed ?? MISSING_VALUE;
+  const spiral = as.spiral ?? MISSING_VALUE;
 
   const fmtIssues = (list) =>
     Array.isArray(list) && list.length ? list.map((i) => `#${i}`).join(', ') : '—';
   const closedList = fmtIssues(issues_closed);
   const createdList = fmtIssues(issues_created);
   const followList = fmtIssues(follow_ups_filed);
-  const commitCount = Array.isArray(commits) ? commits.length : 0;
+  // #969 LOW-1: an ABSENT `commits` is "not recorded", an EMPTY one is
+  // "recorded, and there were none". `commits` is not in
+  // RENDERABLE_SESSION_FIELDS_V3, so absence is reachable — and the old `: 0`
+  // published the second answer to the first question. A present-but-empty
+  // array keeps rendering `0`: that IS a measured zero, exactly the value the
+  // ABSENT-IS-NOT-ZERO banner says must survive.
+  const commitCount = Array.isArray(commits) ? commits.length : MISSING_VALUE;
   const testsDelta =
     typeof tests_total_pre === 'number' && typeof tests_total_post === 'number'
       ? `${tests_total_pre} → ${tests_total_post}`
@@ -328,7 +583,9 @@ export function generateSessionNoteV3(entry, options = {}) {
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
   const noteId = slugifyIdSafe(session_id) ?? session_id;
-  const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', 'verified'])}]`;
+  // #909: the real ledger status, mapped into the vault enum — never hard-coded.
+  const vaultStatus = vaultStatusForSession(entry);
+  const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
 
   const platformBullet = platform === null || platform === undefined || platform === '' ? '' : ` · **Platform:** ${platform}`;
   const branchLine = branch ? ` · **Branch:** ${branch}` : '';
@@ -342,7 +599,7 @@ export function generateSessionNoteV3(entry, options = {}) {
 id: ${noteId}
 type: session
 title: ${title}
-status: verified
+status: ${vaultStatus}
 created: ${created}
 updated: ${updated}
 tags: ${tags}
@@ -352,9 +609,9 @@ ${fmLine('source-repo', repoNs)}_generator: ${GENERATOR_MARKER}
 # Session ${session_id}
 
 - **Type:** ${session_type}${branchLine}${platformBullet}
-- **Duration:** ${durationMin}m (${started_at} → ${completed_at})
+- **Duration:** ${durationLabel} (${started_at} → ${completed_at})
 - **Waves:** ${waves} · **Agents:** ${agentsValue} · **Commits:** ${commitCount}
-- **Effectiveness:** planned=${planned_issues ?? 'n/a'}, completed=${completed}, carryover=${carryover}, emergent=${emergent}, rate=${ratePercent}
+- **Effectiveness:** planned=${planned_issues ?? MISSING_VALUE}, completed=${completed}, carryover=${carryover}, emergent=${emergent}, rate=${ratePercent}
 - **Tests:** ${testsDelta}
 - **Issues closed:** ${closedList}
 - **Issues created:** ${createdList}