session-orchestrator 5.10.0 → 5.12.0

package/scripts/lib/session-end/vault-orphans.mjs

@@ -0,0 +1,205 @@
+/**
+ * vault-orphans.mjs - Phase 3.7e Vault Orphans (#1563).
+ *
+ * Lists the untracked files in the Meta-Vault that were modified since this
+ * session started, so the closing session can NAME what it may have left
+ * behind there.
+ *
+ * Why this exists (measured 2026-10-11): one vault checkout had accumulated 268
+ * untracked files over five days - website audits, session reports, reviews,
+ * lead handovers - written by sessions of OTHER repos into their configured
+ * `vault-dir`. None of them was ever committed: a session's close commits only
+ * in its own repo, and vault-mirror auto-commits only its own generator-marked
+ * files (`scripts/lib/vault-mirror/auto-commit.mjs`). The writing session is the
+ * only one that knows it wrote them, and nothing made it look.
+ *
+ * THE IRON RULE: this module PROPOSES, it never DISPOSES. Its only git
+ * invocation is the read-only `ls-files --others --exclude-standard -z`. No
+ * add, commit, rm, mv, clean, stash; no file is written, moved or deleted. The
+ * vault is another repo with its own rules (PSA-003).
+ *
+ * The return field is named `candidates`, not `orphans`: mtime is a HINT, not
+ * proof of ownership. A concurrent session of another repo may have written the
+ * same file in the same window. The coordinator names them and records one Open
+ * Question; it never acts on them.
+ *
+ * Three states, never two (a missing measurement must not look like zero):
+ *   - `{ status: 'ok', total: 0 }`   - measured, nothing found
+ *   - `{ status: 'ok', total: N }`   - measured, N candidates
+ *   - `{ status: 'unavailable' }`    - could not measure (no vault dir, not a
+ *                                      git repo, git failed). Never reported as
+ *                                      "no orphans".
+ *
+ * Exclusion - what another writer already owns: any file whose first 4 KB
+ * carries a `_generator: session-orchestrator-` frontmatter line. Census
+ * 2026-10-11 @ 686e2c12 (`rg -n "GENERATOR_MARKER\s*=" scripts/`): four marker
+ * values, all with that prefix - `vault-mirror@1` (40-learnings/, 50-sessions/,
+ * monthly rollups), `vault-status-narrative@1` (01-projects/<slug>/
+ * _session-narrative.md), `active-sessions@1` (01-projects/_active-sessions.md),
+ * `gitlab-portfolio@1`. The match is line-anchored so a hand-written note that
+ * merely QUOTES the marker in prose is still reported.
+ *
+ * There is deliberately NO blanket exclusion of `40-learnings/` / `50-sessions/`:
+ * vault-mirror owns only the MARKED files there. `autoCommitVaultMirror` treats
+ * an unmarked staged file in those dirs as an offender and skips its whole
+ * commit, so an unmarked untracked file there is owned by nobody AND blocks the
+ * mirror - the last thing to hide.
+ *
+ * Never throws. DI seams (#580-DI-001), synchronous like the Phase 4b sibling
+ * ./worktree-orphan-sweep.mjs: `execFileFn` (default `execFileSync`) and
+ * `statFn` (default `lstatSync` - a symlink is reported as itself, never
+ * followed out of the vault). Every git call passes an args ARRAY, no shell
+ * (#577 HARDEN-001).
+ */
+
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { closeSync, lstatSync, openSync, readSync } from 'node:fs';
+
+import { redactHomeDir } from '../common.mjs';
+
+/** Upper bound on the returned `candidates` list; `total` still counts all. */
+export const MAX_CANDIDATES = 200;
+
+/** Bytes read per file for the generator check - same window as auto-commit.mjs. */
+const HEAD_BYTES = 4096;
+
+/** A frontmatter line naming one of this plugin's generators. */
+const GENERATOR_LINE_RE = /^_generator:[ \t]*session-orchestrator-/m;
+
+/**
+ * Env vars that retarget git away from `-C <dir>`. An inherited `GIT_DIR` beats
+ * `-C` (incident 2026-08-19), which here would list ANOTHER repo's untracked
+ * files as vault candidates. Stripped for the one git call below.
+ */
+const REPO_REDIRECT_ENV = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR'];
+
+/**
+ * Ceiling for git's NUL-separated path list: 16 MiB is ~150k paths at ~100
+ * bytes. Past it, execFileSync throws ENOBUFS and the result is `unavailable`
+ * (could not measure), never a silently cut list. Revisit if a vault ever
+ * reports that reason.
+ */
+const LS_FILES_MAX_BUFFER = 16 * 1024 * 1024;
+
+/**
+ * A vault on a hung network filesystem must not stall /close: past this the
+ * call is killed and the result is `unavailable` (git-failed). 20k untracked
+ * files took 0.46 s (2026-10-11), so 20 s is a hang, not a slow vault.
+ */
+const LS_FILES_TIMEOUT_MS = 20_000;
+
+/** @param {string} absPath @returns {boolean} true when the head names one of our generators */
+function isGeneratorOwned(absPath) {
+  let fd;
+  try {
+    fd = openSync(absPath, 'r');
+    const buf = Buffer.alloc(HEAD_BYTES);
+    const n = readSync(fd, buf, 0, HEAD_BYTES, 0);
+    return GENERATOR_LINE_RE.test(buf.subarray(0, n).toString('utf8'));
+  } catch {
+    // Unreadable -> not provably someone else's. This module only REPORTS, so
+    // the safe direction is to show the file, not to hide it.
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} reason
+ * @param {string} [detail]
+ * @returns {{status: 'unavailable', reason: string, detail?: string, candidates: []}}
+ */
+function unavailable(reason, detail) {
+  return detail ? { status: 'unavailable', reason, detail, candidates: [] } : { status: 'unavailable', reason, candidates: [] };
+}
+
+/**
+ * Find untracked vault files modified at or after `sinceMs`.
+ *
+ * @param {object} [opts]
+ * @param {string} opts.vaultDir - Vault working-tree root (already tilde-expanded).
+ * @param {number} opts.sinceMs - Session start, epoch ms. Files with an older
+ *   mtime are not candidates.
+ * @param {Function} [opts.execFileFn] - execFileSync seam: (file, args, options) => string.
+ * @param {Function} [opts.statFn] - lstatSync seam: (absPath) => { mtimeMs, isFile() }.
+ * @returns {{status: 'ok', candidates: Array<{path: string, mtimeMs: number}>,
+ *   total: number, truncated: boolean, untracked: number}
+ *   | {status: 'unavailable', reason: string, detail?: string, candidates: []}}
+ *   `path` is vault-relative as git reports it. `total` counts every candidate,
+ *   `candidates` holds at most MAX_CANDIDATES of them (sorted by path),
+ *   `untracked` is everything git listed before the mtime and generator filters.
+ */
+export function findVaultOrphans({ vaultDir, sinceMs, execFileFn, statFn } = {}) {
+  try {
+    if (typeof vaultDir !== 'string' || vaultDir.trim() === '') return unavailable('no-vault-dir');
+    if (typeof sinceMs !== 'number' || !Number.isFinite(sinceMs)) return unavailable('invalid-since');
+
+    const exec = typeof execFileFn === 'function' ? execFileFn : execFileSync;
+    const stat = typeof statFn === 'function' ? statFn : lstatSync;
+    const root = path.resolve(vaultDir);
+
+    const env = { ...process.env };
+    for (const key of REPO_REDIRECT_ENV) delete env[key];
+
+    // -- THE ONLY GIT CALL - read-only --------------------------------------
+    let out;
+    try {
+      out = exec('git', ['-C', root, 'ls-files', '--others', '--exclude-standard', '-z'], {
+        encoding: 'utf8',
+        env,
+        maxBuffer: LS_FILES_MAX_BUFFER,
+        timeout: LS_FILES_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      const stderr = typeof err?.stderr === 'string' ? err.stderr : String(err?.stderr ?? '');
+      const reason = /not a git repository/i.test(stderr) ? 'not-a-git-repo' : 'git-failed';
+      const firstLine = redactHomeDir(stderr.split('\n').find((l) => l.trim() !== '') ?? err?.code ?? '');
+      return unavailable(reason, typeof firstLine === 'string' ? firstLine.trim().slice(0, 200) : undefined);
+    }
+    if (typeof out !== 'string') return unavailable('git-failed', 'non-string git output');
+
+    const untrackedPaths = out.split('\0').filter((p) => p !== '');
+
+    // Cost is linear in the untracked count: one lstat per path, plus one 4 KB
+    // read per path that passes the mtime filter (cheapest filter first). Fine
+    // for the measured 268; revisit if a close reports more than ~10k untracked
+    // files, where the per-file read would start to show in /close time.
+    const all = [];
+    for (const rel of untrackedPaths) {
+      const abs = path.join(root, rel);
+      let st;
+      try {
+        st = stat(abs);
+      } catch {
+        // Vanished between listing and stat (a concurrent writer moved it):
+        // nothing left to name.
+        continue;
+      }
+      const mtimeMs = Number(st?.mtimeMs);
+      if (!Number.isFinite(mtimeMs) || mtimeMs < sinceMs) continue;
+      if (typeof st.isFile === 'function' && st.isFile() && isGeneratorOwned(abs)) continue;
+      all.push({ path: rel, mtimeMs });
+    }
+
+    all.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return {
+      status: 'ok',
+      candidates: all.slice(0, MAX_CANDIDATES),
+      total: all.length,
+      truncated: all.length > MAX_CANDIDATES,
+      untracked: untrackedPaths.length,
+    };
+  } catch (err) {
+    // Defensive catch-all - this probe must never throw into /close.
+    return unavailable('internal-error', String(err?.message ?? err).slice(0, 200));
+  }
+}

package/scripts/lib/session-invocation.mjs

@@ -3,15 +3,26 @@
  * This is a text boundary, not a shell/option parser: quotes and command syntax
  * in the context remain data. `unknown` is a ledger value, never a live mode.
  *
+ * A bare `/session` defaults to `deep`. In a repo without any session history
+ * of its own that default is not silent: the result carries
+ * `defaultReason: 'no-session-history'`, and the caller asks for task and mode
+ * first (#1561). `hasHistory` left undefined means "not measured" and keeps
+ * the plain default.
+ *
  * @param {string} [argumentsText] Complete text following /session.
- * @returns {{sessionType: string, context: string, profile?: string, invalidMode?: string}}
+ * @param {{hasHistory?: boolean}} [options]
+ * @returns {{sessionType: string, context: string, profile?: string, invalidMode?: string, defaultReason?: string}}
  */
-export function resolveSessionInvocation(argumentsText = '') {
+export function resolveSessionInvocation(argumentsText = '', { hasHistory } = {}) {
   if (typeof argumentsText !== 'string') {
     throw new TypeError('session invocation arguments must be a string');
   }
   const [_, mode, context = ''] = argumentsText.trimStart().match(/^(\S+)(?:\s+([\s\S]*))?$/u) ?? [];
-  if (mode === undefined) return { sessionType: 'deep', context: '' };
+  if (mode === undefined) {
+    return hasHistory === false
+      ? { sessionType: 'deep', context: '', defaultReason: 'no-session-history' }
+      : { sessionType: 'deep', context: '' };
+  }
   if (mode === 'ultradeep') return { sessionType: 'deep', profile: 'ultradeep', context };
   if (['housekeeping', 'feature', 'deep'].includes(mode)) {
     return { sessionType: mode, context };

package/scripts/lib/session-lock.mjs

@@ -527,8 +527,10 @@ export function readLockDetailed(opts = {}) {
  *   result — this keeps acquire() synchronous.
  *
  * Returns one of:
- *   { ok: true, lock, exclusivityClass? }
- *       — lock created
+ *   { ok: true, lock, exclusivityClass?, ownerProof }
+ *       — lock created. `ownerProof` reports the owner-proof rewrite that
+ *         follows every successful lock write (#1541, see withOwnerProof()):
+ *         `{ ok: true }` or `{ ok: false, reason }` — never thrown.
  *   { ok: false, reason: 'active', existingLock, ageHours, exclusivityClass? }
  *       — local lock held: its last_heartbeat is within ttl_hours. `ageHours`
  *         is the age from `started_at` (null when unparseable). `existingLock`
@@ -777,7 +779,7 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
     const createResult = createSessionLockExclusive(lockFile, lock);
 
     if (createResult.ok) {
-      return { ok: true, lock, exclusivityClass: callerClass };
+      return withOwnerProof({ ok: true, lock, exclusivityClass: callerClass }, repoRoot);
     }
     if (createResult.reason === 'fs-error') {
       return { ok: false, reason: 'fs-error', error: createResult.error, exclusivityClass: callerClass };
@@ -804,7 +806,8 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
  * Call only after the user has explicitly authorised stale-lock takeover.
  *
  * Returns:
- *   { ok: true, lock, replacedLock? }               — lock written (replacedLock present if one was overwritten)
+ *   { ok: true, lock, replacedLock?, ownerProof }   — lock written (replacedLock present if one was overwritten;
+ *                                                     ownerProof as on acquire(), #1541)
  *   { ok: false, reason: 'missing-session-id' }     — no usable `sessionId` given; NOTHING was written
  *   { ok: false, reason: 'fs-error', ... }          — filesystem failure
  *
@@ -833,6 +836,48 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
  *
  * @param {{ sessionId: string, mode: string, ttlHours?: number, repoRoot?: string, semanticSessionId?: string, onlyIfNotLive?: boolean }} args
  */
+/**
+ * Rewrite `.orchestrator/runtime/lock-owner-proof.json` for a lock this module
+ * has JUST written, and report the outcome on the result (#1541).
+ *
+ * Invariant: proof = current lock. Before #1541 only the SessionStart bootstrap
+ * wrote the proof, so a lock taken on the prose path (Phase 1.2 `acquire()`
+ * after a `/close` in the same conversation, or a force-take / reclaim) left
+ * the PREVIOUS lock's proof on disk — and `release()` answered
+ * `proof-mismatch` for the session's own lock at its next `/close`.
+ *
+ * Called only on the `ok: true` paths, directly after the lock write, with the
+ * same `repoRoot` the lock path was resolved from (both fall back to
+ * `process.cwd()`), so the proof lands beside the lock it describes. The
+ * bootstrap's own later writeOwnerProof() on the enriched lock yields the same
+ * triple (enrichment never touches pid/host/started_at) — idempotent.
+ *
+ * Never throws and never turns `ok: true` into a failure: the lock IS held, and
+ * a missing proof only degrades `/close` to the session_id-only release.
+ *
+ * Ceiling (BV-004): two plain forceAcquire() calls racing on one path are
+ * last-writer-wins for the lock AND the proof, and the two writes can
+ * interleave (A lock, B lock, B proof, A proof). The proof then names A while B
+ * holds the lock — the same state as before #1541, and safe: release() still
+ * gates on the raw session_id first, so the mismatched proof can only refuse a
+ * release, never grant one. Revisit if `release-proof-mismatch` shows up after
+ * a force-take.
+ *
+ * Known limit: the proof is one file per repo and identifies the process that
+ * last wrote the lock, never the conversation. Twins sharing one raw
+ * session_id (two terminals resuming the same conversation) are therefore
+ * indistinguishable to it — either can release after the other force-took.
+ *
+ * @param {{ ok: true, lock: object }} result
+ * @param {string|undefined} repoRoot
+ * @returns {object} the same result object, with `ownerProof` set
+ */
+function withOwnerProof(result, repoRoot) {
+  const w = writeOwnerProof({ repoRoot, lock: result.lock });
+  result.ownerProof = w.ok ? { ok: true } : { ok: false, reason: w.reason };
+  return result;
+}
+
 /**
  * A `sessionId` is usable only when it is a non-blank string. ONE predicate,
  * shared by acquire() and forceAcquire(), so the two entry points cannot drift
@@ -863,7 +908,7 @@ export function forceAcquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, re
 
     const result = { ok: true, lock };
     if (replacedLock !== null) result.replacedLock = replacedLock;
-    return result;
+    return withOwnerProof(result, repoRoot);
   } catch (err) {
     return { ok: false, reason: 'fs-error', error: err.message };
   }
@@ -948,7 +993,7 @@ function reclaimIfNotLive({ sessionId, mode, ttlHours, repoRoot, semanticSession
     if (created.ok) {
       const result = { ok: true, lock };
       if (moved !== null) result.replacedLock = moved;
-      return result;
+      return withOwnerProof(result, repoRoot);
     }
     if (created.reason === 'exists') return reacquire();
     return created;
@@ -1108,10 +1153,12 @@ export function isLockOwnedByProof(lock, proof) {
  * persistence at lock genesis; Part 2, the on-session-end consumption side,
  * is a separate change).
  *
- * Intended caller: `bootstrapLock()` (hooks/_lib/lock-bootstrap.mjs)
- * immediately after its enriched-lock write — the `lock` argument there is
- * byte-identical to the on-disk lock, so the proof it yields will verify via
- * `isLockOwnedByProof()` against any later re-read of that same lock.
+ * Callers: `acquire()` / `forceAcquire()` on every `ok: true` lock write
+ * (#1541, via withOwnerProof()), and `bootstrapLock()`
+ * (hooks/_lib/lock-bootstrap.mjs) again immediately after its enriched-lock
+ * write. In every case the `lock` argument is byte-identical to the on-disk
+ * lock, so the proof it yields will verify via `isLockOwnedByProof()` against
+ * any later re-read of that same lock.
  *
  * Envelope shape (schema_version 1):
  *   {

package/scripts/lib/session-record-repair.mjs

@@ -108,13 +108,15 @@ const INCOMPLETE_FIELD_ORDER = Object.freeze([
   'total_agents',
   'total_files_changed',
 ]);
-// `timestamp_precision` (#1442) deliberately adds NOTHING to the list above: a
-// truncated timestamp is still a measurement (exact to the millisecond), not a
-// default. Listing it would make consumers discard a real value —
-// `sessions-staleness-banner.mjs` returns null for any timestamp named in
-// `_backfill_incomplete_fields`, `session-close-backfill.mjs` keys on
-// `includes('started_at')`. The sub-millisecond original survives in the
-// `_<field>_raw` sidecar instead.
+// `timestamp_precision` (#1442) and `timestamp_offset` (#1525) deliberately add
+// NOTHING to the list above: a truncated or UTC-converted timestamp is still a
+// measurement (exact to the millisecond), not a default. Listing it would make
+// consumers discard a real value — `sessions-staleness-banner.mjs` returns null
+// for any timestamp named in `_backfill_incomplete_fields`,
+// `session-close-backfill.mjs` keys on `includes('started_at')`. The original
+// spelling survives in the `_<field>_raw` sidecar instead. Two classes because
+// the losses differ: `precision` drops sub-ms digits, `offset` drops nothing
+// but the zone spelling (the instant is kept exactly).
 
 /**
  * Timestamp fields `validateSession` holds to `ISO_8601_UTC_MS_RE`
@@ -124,11 +126,15 @@ const INCOMPLETE_FIELD_ORDER = Object.freeze([
 const MS_PRECISION_FIELDS = Object.freeze(['started_at', 'completed_at', 'lease_acquired_at']);
 
 /**
- * ISO-8601 UTC with MORE than three fractional digits and exactly `Z` or
- * `+00:00` (#1525). Group 1 is the value cut at the millisecond. Nonzero
- * offsets, other timezone spellings and shorter fractions stay unrepaired.
+ * Strict ISO-8601 timestamp the repair may normalize (#1525): seconds required,
+ * fraction optional and of any length, zone exactly `Z` or `±HH:MM`. Anything
+ * looser (`+0000`, `+00`, lowercase `z`, no zone) stays unrepaired, so the
+ * lenient `Date.parse` never gets to decide what a value meant.
+ * Groups: 1 wall-clock date-time to the second, 2 fraction digits, 3 zone,
+ * 4 offset sign, 5 offset hours, 6 offset minutes.
  */
-const ISO_UTC_SUB_MS_RE = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3})\d+(?:Z|\+00:00)$/;
+const ISO_REPAIRABLE_RE =
+  /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?(Z|([+-])(\d{2}):(\d{2}))$/;
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -144,23 +150,45 @@ function isCount(v) {
 }
 
 /**
- * Cut a sub-millisecond ISO-8601 UTC timestamp to milliseconds. TRUNCATES,
- * never rounds: `.9999Z` must not roll into the next second, and truncation is
- * monotone, so `completed_at >= started_at` survives on every pair it held on.
+ * Normalize a timestamp to the validator's UTC-millisecond shape (#1442, #1525).
+ *
+ * - `precision`: a fraction of other than 0 or 3 digits. Sub-millisecond
+ *   digits are TRUNCATED, never rounded: `.9999Z` must not roll into the next
+ *   second, and truncation is monotone, so `completed_at >= started_at`
+ *   survives on every pair it held on. Shorter fractions are zero-padded.
+ * - `offset`: any zone spelled other than `Z`. Converting `±HH:MM` to UTC keeps
+ *   the instant exactly (offsets are whole minutes), so it is lossless and
+ *   commutes with the truncation above.
  *
  * @param {unknown} value
- * @returns {string|null} the truncated value, or null when there is nothing to cut
+ * @returns {null | {invalid: true} | {value: string, precision: boolean, offset: boolean}}
+ *   null when there is nothing to normalize (not a string, not the strict
+ *   shape, or already canonical); `{invalid: true}` when the shape matches but
+ *   the calendar/clock components or the offset are out of range.
  */
-function truncateToMs(value) {
+function normalizeTimestamp(value) {
   if (typeof value !== 'string') return null;
-  const m = ISO_UTC_SUB_MS_RE.exec(value);
+  const m = ISO_REPAIRABLE_RE.exec(value);
   if (!m) return null;
-  const canonical = `${m[1]}Z`;
-  const ms = Date.parse(canonical);
+  const [, wall, fraction = '', zone, sign, offH, offM] = m;
+  const precision = fraction.length !== 0 && fraction.length !== 3;
+  const offset = zone !== 'Z';
+  if (!precision && !offset) return null; // already what the validator accepts
+  const wallCanonical = `${wall}.${fraction.slice(0, 3).padEnd(3, '0')}Z`;
+  const wallMs = Date.parse(wallCanonical);
   // Date.parse rolls over e.g. April 31, non-leap February 29 and 24:00.
   // Equality with the original calendar components refuses those repairs.
-  if (!Number.isFinite(ms) || new Date(ms).toISOString() !== canonical) return null;
-  return canonical;
+  if (!Number.isFinite(wallMs) || new Date(wallMs).toISOString() !== wallCanonical) {
+    return { invalid: true };
+  }
+  let offsetMin = 0;
+  if (offset) {
+    if (Number(offH) > 23 || Number(offM) > 59) return { invalid: true };
+    offsetMin = (sign === '-' ? -1 : 1) * (Number(offH) * 60 + Number(offM));
+  }
+  const utc = new Date(wallMs - offsetMin * 60_000);
+  if (!Number.isFinite(utc.getTime())) return { invalid: true };
+  return { value: utc.toISOString(), precision, offset };
 }
 
 function orderIncompleteFields(fields) {
@@ -377,12 +405,14 @@ export function repairRecord(record) {
   // `started_at` — a microsecond `started_at` would otherwise be copied into
   // `completed_at` and spread the defect instead of fixing it.
   let precisionCut = false;
+  let offsetNormalized = false;
   for (const key of MS_PRECISION_FIELDS) {
-    const truncated = truncateToMs(out[key]);
-    if (truncated === null) continue;
+    const norm = normalizeTimestamp(out[key]);
+    if (norm === null || 'invalid' in norm) continue;
     preserveRaw(out, key, record[key], rescued);
-    out[key] = truncated;
-    precisionCut = true;
+    out[key] = norm.value;
+    precisionCut ||= norm.precision;
+    offsetNormalized ||= norm.offset;
   }
 
   // -- completed_at ---------------------------------------------------------
@@ -396,18 +426,20 @@ export function repairRecord(record) {
     preserveRaw(out, 'completed_at', record.completed_at, rescued);
     const endedMs = typeof out.ended_at === 'string' ? Date.parse(out.ended_at) : NaN;
     const startedMs = Date.parse(out.started_at);
-    const endedTruncated = truncateToMs(out.ended_at);
+    const endedNorm = normalizeTimestamp(out.ended_at);
     if (typeof out.ended_at === 'string' &&
-        (!Number.isFinite(endedMs) ||
-         (ISO_UTC_SUB_MS_RE.test(out.ended_at) && endedTruncated === null))) {
+        (!Number.isFinite(endedMs) || (endedNorm !== null && 'invalid' in endedNorm))) {
       // Preserve an invalid legacy measurement for the final schema gate to
       // reject; do not turn it into a valid default or a rolled-over date.
       out.completed_at = out.ended_at;
     } else if (Number.isFinite(endedMs) && Number.isFinite(startedMs) && endedMs >= startedMs) {
       // The COPY is cut to milliseconds; `ended_at` itself is not a validated
       // field and keeps its original bytes, so nothing needs a sidecar here.
-      if (endedTruncated !== null) precisionCut = true;
-      out.completed_at = endedTruncated ?? out.ended_at;
+      if (endedNorm !== null) {
+        precisionCut ||= endedNorm.precision;
+        offsetNormalized ||= endedNorm.offset;
+      }
+      out.completed_at = endedNorm?.value ?? out.ended_at;
     } else {
       out.completed_at = out.started_at;
     }
@@ -415,6 +447,7 @@ export function repairRecord(record) {
     incomplete.add('completed_at');
   }
   if (precisionCut) defects.push('timestamp_precision');
+  if (offsetNormalized) defects.push('timestamp_offset');
 
   if (defects.length === 0) {
     return { record, defects: [], incompleteFields: [], changed: false };

package/scripts/lib/session-registry.mjs

@@ -38,7 +38,7 @@ import crypto from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import { digestSha256 } from './crypto-digest-utils.mjs';
 
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, mkdirSync, realpathSync } from 'node:fs';
 
 import { utcTimestamp, appendJsonl } from './common.mjs';
 import { resolvePrivateConfigDir } from './config/private-config-dir.mjs';
@@ -89,14 +89,24 @@ function entryPath(sessionId) {
 // ---------------------------------------------------------------------------
 
 /**
- * Stable SHA-256 hex of an absolute path. Used so registry entries can be
+ * Stable SHA-256 hex of a canonical repo path. Used so registry entries can be
  * correlated by repo without exposing local filesystem layout.
  */
 export function repoPathHash(absPath) {
   if (typeof absPath !== 'string' || absPath.length === 0) {
     throw new TypeError('repoPathHash: absPath must be a non-empty string');
   }
-  return digestSha256(path.resolve(absPath));
+  return digestSha256(resolveRepoPath(absPath));
+}
+
+/** Resolve symlinks and on-disk casing; unavailable paths keep their old identity. */
+function resolveRepoPath(repoPath) {
+  const resolved = path.resolve(repoPath);
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
 }
 
 function _assertSessionId(sessionId) {
@@ -255,7 +265,7 @@ export async function registerSelf(opts) {
     pid: opts.pid ?? process.pid,
     platform: opts.platform ?? null,
     repo_path_hash: repoPathHash(projectRoot),
-    repo_name: path.basename(path.resolve(projectRoot)),
+    repo_name: path.basename(resolveRepoPath(projectRoot)),
     branch: opts.branch ?? null,
     started_at: now,
     last_heartbeat: now,

package/scripts/lib/session-schema/constants.mjs

@@ -252,6 +252,14 @@ export const OPTIONAL_FIELDS = Object.freeze([
   // 2026-10-01), so the counters say which of the two it is.
   'cost_records_priced',
   'cost_records_total',
+  // #1470 Pkt 4/6 — what `total_cost_usd` is and which price table produced
+  // the cost fields. Merged by scripts/emit-session.mjs from
+  // scripts/lib/telemetry/pricing.mjs (`COST_BASIS`, `PRICING_TABLE_DATE`):
+  // `cost_basis` only beside a written `total_cost_usd`, `pricing_table_date`
+  // beside the cost counters. Absent on every record before #1470 — such a
+  // cost is not thereby a verified payment either.
+  'cost_basis',
+  'pricing_table_date',
   // #986 — shape-checked by `_validateOptionalFields` since before this list
   // existed, never declared until the census test made the gap visible.
   'discovery_stats',

package/scripts/lib/session-schema/validator.mjs

@@ -26,6 +26,17 @@ import {
 /** Valid values for the optional `expected_cost_tier` field (ADR-364). */
 const EXPECTED_COST_TIERS = Object.freeze(['quick', 'standard', 'deep']);
 
+/**
+ * Valid values for the optional `cost_basis` field (#1470 Pkt 4). Must contain
+ * `COST_BASIS` from scripts/lib/telemetry/pricing.mjs — the value emit-session
+ * writes beside `total_cost_usd`. There is deliberately no payment value: no
+ * writer can see what was actually billed.
+ */
+const COST_BASES = Object.freeze(['api-list-equivalent']);
+
+/** `pricing_table_date` (#1470 Pkt 6): a calendar date, `YYYY-MM-DD`. */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
 /**
  * Valid values for the optional `status` field (Epic #724 C1).
  * `completed`  — record written by a normal /close flow.
@@ -456,6 +467,28 @@ function _validateOptionalFields(entry) {
     );
   }
 
+  // #1470 Pkt 4/6 — what the cost figure is and which price table produced it.
+  if (entry.cost_basis !== undefined && entry.cost_basis !== null) {
+    if (!COST_BASES.includes(entry.cost_basis)) {
+      throw new ValidationError(
+        `cost_basis must be one of ${COST_BASES.join('|')} or null, got: ${entry.cost_basis}`
+      );
+    }
+  }
+  if (entry.pricing_table_date !== undefined && entry.pricing_table_date !== null) {
+    if (
+      typeof entry.pricing_table_date !== 'string' ||
+      !ISO_DATE_RE.test(entry.pricing_table_date) ||
+      // Round-trip, not Date.parse alone: V8 rolls 2026-02-30 over to March.
+      Number.isNaN(Date.parse(`${entry.pricing_table_date}T00:00:00Z`)) ||
+      new Date(`${entry.pricing_table_date}T00:00:00Z`).toISOString().slice(0, 10) !== entry.pricing_table_date
+    ) {
+      throw new ValidationError(
+        `pricing_table_date must be an ISO date (YYYY-MM-DD) or null, got: ${entry.pricing_table_date}`
+      );
+    }
+  }
+
   // Epic #724 C1 — SessionEnd close-through backfill provenance fields.
   // All additive-optional; null/absent passes without further checks so that
   // pre-#724 records (and every normally-closed record) validate cleanly.