session-orchestrator 5.10.0 → 5.11.0

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-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.

package/scripts/lib/subagents-schema.mjs

@@ -55,6 +55,8 @@
  *   total_cost_usd    number  | null — native total cost in USD (#624, fractional,
  *                                      best-effort: null when the harness does not
  *                                      expose it; no rate table is applied)
+ *   cost_basis        'api-list-equivalent' | null — explicitly supplied cost
+ *                                      provenance; null means unknown (#1543)
  *
  * OTel aliases (optional, stop-only, additive — #411, schema_version=1 backwards-compat):
  *   gen_ai.usage.input_tokens   integer | null — RAW UNCACHED prompt tokens (OTel
@@ -69,6 +71,7 @@
 import { readFile, appendFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { COST_BASIS } from './telemetry/pricing.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -267,6 +270,11 @@ export function validateSubagent(entry, options = {}) {
     }
   }
 
+  // #1543 additive: never infer provenance from a native dollar value.
+  if (entry.cost_basis !== undefined && entry.cost_basis !== null && entry.cost_basis !== COST_BASIS) {
+    throw new ValidationError(`cost_basis must be ${COST_BASIS} or null`, 'cost_basis');
+  }
+
   // OTel alias — #411 additive, schema_version=1 backwards-compat
   const otelInputTokens = entry['gen_ai.usage.input_tokens'];
   if (otelInputTokens !== undefined && otelInputTokens !== null) {
@@ -334,6 +342,7 @@ export function normalizeSubagent(entry) {
     model: entry.model ?? null,
     // total_cost_usd — #624 additive, best-effort native cost (null when absent)
     total_cost_usd: entry.total_cost_usd ?? null,
+    cost_basis: entry.cost_basis ?? null,
     // OTel alias — #411 additive, schema_version=1 backwards-compat
     'gen_ai.usage.input_tokens': entry['gen_ai.usage.input_tokens'] ?? null,
     'gen_ai.usage.cache_read_input_tokens': entry['gen_ai.usage.cache_read_input_tokens'] ?? null,

package/scripts/lib/telemetry/pricing.mjs

@@ -62,6 +62,17 @@
  */
 export const PRICING_TABLE_DATE = '2026-09-29';
 
+/**
+ * What a dollar figure computed from this table IS (#1470 Pkt 4): the API
+ * list-price equivalent of the metered tokens — never a payment. Subscription
+ * quota, purchased credits and what was actually billed are not visible to
+ * this module, so a consumer must not present the figure as any of them.
+ * Written beside every persisted cost as `cost_basis`; the session validator's
+ * `COST_BASES` must contain it (pinned by tests/scripts/emit-session.test.mjs).
+ * @type {'api-list-equivalent'}
+ */
+export const COST_BASIS = 'api-list-equivalent';
+
 /**
  * @typedef {Object} PricingRow
  * @property {number} input           - USD per 1M uncached prompt tokens.

package/scripts/measure-context-overhead.sh

@@ -44,6 +44,8 @@
 set -uo pipefail
 
 PROMPT='Antworte nur mit dem Wort: OK'
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+FORMATTER="$SCRIPT_DIR/lib/context-overhead-format.mjs"
 
 measure_one() {
   local dir="$1" label="$2"
@@ -51,29 +53,10 @@ measure_one() {
     printf '%s\tNO-SUCH-DIR\n' "$label"
     return
   fi
-  ( cd "$dir" && claude -p "$PROMPT" --output-format json 2>/dev/null ) | node -e "
-let s = '';
-process.stdin.on('data', (d) => (s += d)).on('end', () => {
-  const label = process.argv[1];
-  try {
-    const j = JSON.parse(s);
-    const u = j.usage || {};
-    const ctx =
-      (u.input_tokens || 0) +
-      (u.cache_creation_input_tokens || 0) +
-      (u.cache_read_input_tokens || 0);
-    process.stdout.write(
-      [label, ctx, u.cache_creation_input_tokens || 0, u.cache_read_input_tokens || 0,
-       u.output_tokens || 0, (j.total_cost_usd || 0).toFixed(4)].join('\t') + '\n',
-    );
-  } catch {
-    process.stdout.write(label + '\tPARSE-ERROR\n');
-  }
-});
-" "$label"
+  ( cd "$dir" && claude -p "$PROMPT" --output-format json 2>/dev/null ) | node "$FORMATTER" -- "$label"
 }
 
-header() { printf 'LABEL\tCONTEXT_TOK\tcache_create\tcache_read\toutput\tUSD\n'; }
+header() { node "$FORMATTER" --header; }
 
 # ── --ablate mode ───────────────────────────────────────────────────
 if [ "${1:-}" = "--ablate" ]; then