session-orchestrator 5.9.0 → 5.11.0

package/scripts/lib/redact-spans.mjs

@@ -9,28 +9,19 @@
  *
  * Behaviour is unchanged from the original: this module is a move, not a rewrite.
  *
- * DELIBERATE SECOND COPY — `check-owner-leakage.mjs` still carries its OWN inline
- * `redactSpans()` and must keep it. That scanner is a documented standalone
- * single-file vendoring target (`.claude/rules/security.md` § "Owner-Privacy
- * Pre-Commit Hook"): consumer repos copy that ONE file, so a static import of this
- * module throws ERR_MODULE_NOT_FOUND in every vendored copy and blocks all commits
- * (proven by the three cases in `tests/husky/pre-commit-owner-leakage.test.mjs`).
- * Unlike CP11's confidential-names helpers, a redaction sink cannot degrade to
- * inert — an absent redaction prints confidential names into a PUBLIC CI log.
- * So: THIS module serves in-tree consumers, the inline copy serves the vendored
- * path, and `tests/lib/redact-spans.test.mjs` pins the two byte-for-byte against
- * each other. Edit one → that drift guard goes red until both agree again.
+ * The owner-leakage scanner remains a standalone vendoring target. Since #1530
+ * it omits offending line content entirely and redacts private filename segments,
+ * so it no longer carries a second copy of this primitive. In-tree consumers
+ * that retain surrounding text use this module; its overlap and ordering
+ * contracts are covered by tests/lib/redact-spans.test.mjs.
  */
 
 /**
  * Redact every confidential-name span from `line`, ORDER-INDEPENDENTLY (Fix 1 + Fix 2).
  *
- * This is the single redaction sink for the confidential-names privacy invariant.
- * In `check-owner-leakage.mjs` it is applied at the print choke-point over EVERY
- * violation's lineContent — not only CP11 hits — because that scanner runs in a
- * PUBLIC GitHub-Actions mirror: a confidential customer/repo name that co-occurs
- * with a CP1–CP10 hit on the same line (e.g. a name beside an RFC1918 IP that
- * fails CP8) would otherwise be echoed verbatim to the public CI log (Fix 1).
+ * Consumers must pass every relevant confidential pattern before emitting text.
+ * This helper matches the supplied text literally; callers handling reversible
+ * encodings must normalize first or omit the sensitive text entirely.
  *
  * ORDER-INDEPENDENCE (Fix 2): a naïve chain of `.replace()` calls is order-dependent
  * — when one configured name is a PREFIX of another (`['acme','acme-corp-secret']`),

package/scripts/lib/role-profile/schema.mjs

@@ -0,0 +1,219 @@
+/**
+ * Offline role-profile evidence contract. Refs #1469.
+ * Validation checks internal consistency, never source authenticity or runtime capability.
+ */
+export const ROLE_PROFILE_CONTRACT_VERSION = 1;
+
+const BINDINGS = new Map([['openai', 'codex-cli'], ['anthropic', 'claude-code']]);
+const DIALECTS = new Map([['openai-reasoning', 'openai'], ['anthropic-effort', 'anthropic']]);
+
+/**
+ * @param {unknown} value JSON data, without accessors or class instances.
+ * @returns {{success: true, data: unknown, diagnostics: object[]} |
+ * {success: false, error: {issues: {code: string, path: (string|number)[], message: string}[]}}}
+ */
+function safeParse(value) {
+  const issues = [];
+  const diagnostics = [];
+  const fail = (code, path, message) => issues.push({ code, path, message });
+  const object = (v, keys, path) => {
+    if (!v || typeof v !== 'object' || Array.isArray(v) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(v))) {
+      fail('INVALID_TYPE', path, 'Expected a plain object');
+      return {};
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(v);
+    if (Object.values(descriptors).some(d => !Object.hasOwn(d, 'value'))) {
+      fail('INVALID_TYPE', path, 'Expected data properties');
+      return {};
+    }
+    for (const key of Reflect.ownKeys(v)) {
+      if (!keys.includes(key)) fail('UNKNOWN_FIELD', [...path, String(key)], 'Unknown field');
+    }
+    for (const key of keys) {
+      if (!Object.hasOwn(v, key)) fail('MISSING_FIELD', [...path, key], 'Required field is missing');
+    }
+    return v;
+  };
+  const string = (v, path) => {
+    if (typeof v !== 'string' || !v.trim()) fail('INVALID_TYPE', path, 'Expected a nonempty string');
+  };
+  const isNull = (v, path) => {
+    if (v !== null) fail('INVALID_RELATION', path, 'Expected null in this evidence state');
+  };
+  const oneOf = (v, values, path) => {
+    if (!values.includes(v)) fail('INVALID_VALUE', path, 'Unsupported discriminator');
+  };
+  const relation = (condition, path, message) => {
+    if (!condition) fail('INVALID_RELATION', path, message);
+  };
+  const evidence = (v, field, path, statuses = ['known', 'unknown']) => {
+    const e = object(v, ['status', field, 'sourceRef', 'reason'], path);
+    oneOf(e.status, statuses, [...path, 'status']);
+    if (e.status === 'unknown') {
+      isNull(e[field], [...path, field]);
+      isNull(e.sourceRef, [...path, 'sourceRef']);
+      string(e.reason, [...path, 'reason']);
+    } else if (statuses.includes(e.status)) {
+      string(e[field], [...path, field]);
+      string(e.sourceRef, [...path, 'sourceRef']);
+      isNull(e.reason, [...path, 'reason']);
+    }
+    return e;
+  };
+
+  const root = object(value, ['contractVersion', 'role', 'taskClass', 'provider', 'transport',
+    'binding', 'model', 'effort', 'harness', 'profile', 'registryVersion', 'selection',
+    'authorization', 'evidence'], []);
+  if (root.contractVersion !== ROLE_PROFILE_CONTRACT_VERSION) {
+    fail('UNSUPPORTED_VERSION', ['contractVersion'], 'Expected contract version 1');
+    return { success: false, error: { issues } };
+  }
+  for (const key of ['role', 'taskClass', 'provider', 'transport']) string(root[key], [key]);
+  const binding = object(root.binding, ['status', 'sourceRef', 'reason'], ['binding']);
+  oneOf(binding.status, ['known', 'unknown'], ['binding', 'status']);
+  if (binding.status === 'known') {
+    string(binding.sourceRef, ['binding', 'sourceRef']);
+    isNull(binding.reason, ['binding', 'reason']);
+    relation(BINDINGS.has(root.provider) && BINDINGS.get(root.provider) === root.transport,
+      ['binding'], 'Known provider/transport binding must match the v1 contract');
+  } else if (binding.status === 'unknown') {
+    isNull(binding.sourceRef, ['binding', 'sourceRef']);
+    string(binding.reason, ['binding', 'reason']);
+  }
+
+  const model = object(root.model, ['requested', 'observed', 'resolution'], ['model']);
+  const requested = object(model.requested, ['kind', 'value'], ['model', 'requested']);
+  oneOf(requested.kind, ['id', 'alias', 'inherit'], ['model', 'requested', 'kind']);
+  if (requested.kind === 'inherit') isNull(requested.value, ['model', 'requested', 'value']);
+  else string(requested.value, ['model', 'requested', 'value']);
+  const observed = evidence(model.observed, 'id', ['model', 'observed']);
+  const resolution = object(model.resolution,
+    ['status', 'baselineId', 'parent', 'sourceRef', 'reason'], ['model', 'resolution']);
+  oneOf(resolution.status, ['exact', 'alias-resolved', 'alias-drift', 'parent-inherit', 'unknown'],
+    ['model', 'resolution', 'status']);
+  if (observed.status === 'unknown') {
+    relation(resolution.status === 'unknown', ['model', 'resolution', 'status'],
+      'Unknown observation must retain unknown resolution');
+  }
+  if (resolution.status === 'unknown') {
+    isNull(resolution.baselineId, ['model', 'resolution', 'baselineId']);
+    isNull(resolution.parent, ['model', 'resolution', 'parent']);
+    isNull(resolution.sourceRef, ['model', 'resolution', 'sourceRef']);
+    string(resolution.reason, ['model', 'resolution', 'reason']);
+  } else if (['exact', 'alias-resolved', 'alias-drift', 'parent-inherit'].includes(resolution.status)) {
+    relation(observed.status === 'known', ['model', 'observed'], 'Resolution requires an observation');
+    string(resolution.sourceRef, ['model', 'resolution', 'sourceRef']);
+    isNull(resolution.reason, ['model', 'resolution', 'reason']);
+    if (resolution.status !== 'alias-drift') isNull(resolution.baselineId, ['model', 'resolution', 'baselineId']);
+    if (resolution.status !== 'parent-inherit') isNull(resolution.parent, ['model', 'resolution', 'parent']);
+    if (resolution.status === 'exact') {
+      relation(requested.kind === 'id' && requested.value === observed.id,
+        ['model', 'resolution'], 'Exact resolution requires the requested ID');
+    } else if (['alias-resolved', 'alias-drift'].includes(resolution.status)) {
+      relation(requested.kind === 'alias', ['model', 'requested', 'kind'], 'Alias resolution requires an alias');
+      if (resolution.status === 'alias-drift') {
+        string(resolution.baselineId, ['model', 'resolution', 'baselineId']);
+        relation(resolution.baselineId !== observed.id, ['model', 'resolution', 'baselineId'],
+          'Alias drift requires a different documented baseline ID');
+      }
+    } else {
+      const parent = object(resolution.parent, ['id', 'sourceRef'], ['model', 'resolution', 'parent']);
+      string(parent.id, ['model', 'resolution', 'parent', 'id']);
+      string(parent.sourceRef, ['model', 'resolution', 'parent', 'sourceRef']);
+      relation(requested.kind === 'inherit' && parent.id === observed.id,
+        ['model', 'resolution'], 'Parent inheritance requires matching parent evidence');
+    }
+  }
+
+  const effort = object(root.effort, ['requested', 'effective', 'support'], ['effort']);
+  const requestedEffort = object(effort.requested, ['provider', 'dialect', 'value'], ['effort', 'requested']);
+  const effective = object(effort.effective,
+    ['provider', 'dialect', 'status', 'value', 'sourceRef', 'reason'], ['effort', 'effective']);
+  const support = object(effort.support, ['status', 'sourceRef', 'reason'], ['effort', 'support']);
+  oneOf(support.status, ['supported', 'unsupported', 'unknown'], ['effort', 'support', 'status']);
+  if (support.status === 'unknown') {
+    isNull(support.sourceRef, ['effort', 'support', 'sourceRef']);
+    string(support.reason, ['effort', 'support', 'reason']);
+  } else if (['supported', 'unsupported'].includes(support.status)) {
+    string(support.sourceRef, ['effort', 'support', 'sourceRef']);
+    isNull(support.reason, ['effort', 'support', 'reason']);
+  }
+  oneOf(effective.status, ['known', 'unknown'], ['effort', 'effective', 'status']);
+  for (const [key, entry] of [['requested', requestedEffort], ['effective', effective]]) {
+    string(entry.provider, ['effort', key, 'provider']);
+    string(entry.dialect, ['effort', key, 'dialect']);
+    relation(entry.provider === root.provider, ['effort', key, 'provider'], 'Effort provider must match the record');
+    if (DIALECTS.has(entry.dialect)) {
+      relation(DIALECTS.get(entry.dialect) === entry.provider, ['effort', key, 'dialect'],
+        'Effort dialect belongs to a different provider');
+    } else {
+      relation(support.status === 'unknown' && effective.status === 'unknown', ['effort', key, 'dialect'],
+        'Unrecognized effort dialect requires unknown support and effective evidence');
+    }
+  }
+  if (requestedEffort.value !== null) string(requestedEffort.value, ['effort', 'requested', 'value']);
+  if (effective.status === 'unknown') {
+    isNull(effective.value, ['effort', 'effective', 'value']);
+    isNull(effective.sourceRef, ['effort', 'effective', 'sourceRef']);
+    string(effective.reason, ['effort', 'effective', 'reason']);
+  } else if (effective.status === 'known') {
+    string(effective.value, ['effort', 'effective', 'value']);
+    string(effective.sourceRef, ['effort', 'effective', 'sourceRef']);
+    isNull(effective.reason, ['effort', 'effective', 'reason']);
+  }
+  if (support.status === 'unsupported') {
+    diagnostics.push({ code: 'UNSUPPORTED_EFFORT', path: ['effort', 'requested', 'value'],
+      message: 'Requested effort is documented as unsupported' });
+    relation(!(effective.status === 'known' && effective.value === requestedEffort.value),
+      ['effort', 'effective'], 'Unsupported requested effort cannot also be claimed effective');
+  }
+
+  const harness = object(root.harness, ['name', 'version'], ['harness']);
+  string(harness.name, ['harness', 'name']);
+  evidence(harness.version, 'value', ['harness', 'version']);
+  const profile = object(root.profile, ['id', 'version'], ['profile']);
+  string(profile.id, ['profile', 'id']);
+  evidence(profile.version, 'value', ['profile', 'version']);
+  evidence(root.registryVersion, 'value', ['registryVersion']);
+  const selection = object(root.selection, ['mode', 'escalationReason'], ['selection']);
+  oneOf(selection.mode, ['profile', 'owner-override', 'escalation'], ['selection', 'mode']);
+  if (selection.mode === 'escalation') string(selection.escalationReason, ['selection', 'escalationReason']);
+  else isNull(selection.escalationReason, ['selection', 'escalationReason']);
+  const auth = object(root.authorization,
+    ['status', 'authority', 'sourceRef', 'scope', 'reason'], ['authorization']);
+  oneOf(auth.status, ['authorized', 'unknown', 'not-required'], ['authorization', 'status']);
+  if (['owner-override', 'escalation'].includes(selection.mode)) {
+    relation(auth.status === 'authorized', ['authorization', 'status'], 'Selection requires owner authorization evidence');
+  }
+  if (auth.status === 'authorized') {
+    relation(auth.authority === 'owner', ['authorization', 'authority'], 'Authorization authority must be owner');
+    string(auth.sourceRef, ['authorization', 'sourceRef']);
+    isNull(auth.reason, ['authorization', 'reason']);
+    const scope = object(auth.scope, ['role', 'provider', 'transport', 'model', 'effort'], ['authorization', 'scope']);
+    for (const key of ['role', 'provider', 'transport']) {
+      string(scope[key], ['authorization', 'scope', key]);
+      relation(scope[key] === root[key], ['authorization', 'scope', key], 'Authorization scope must cover this record');
+    }
+    const scopedModel = object(scope.model, ['kind', 'value'], ['authorization', 'scope', 'model']);
+    for (const key of ['kind', 'value']) relation(scopedModel[key] === requested[key],
+      ['authorization', 'scope', 'model', key], 'Authorization must cover the model request');
+    const scopedEffort = object(scope.effort, ['provider', 'dialect', 'value'], ['authorization', 'scope', 'effort']);
+    for (const key of ['provider', 'dialect', 'value']) relation(scopedEffort[key] === requestedEffort[key],
+      ['authorization', 'scope', 'effort', key], 'Authorization must cover the effort request');
+  } else if (['unknown', 'not-required'].includes(auth.status)) {
+    for (const key of ['authority', 'sourceRef', 'scope']) isNull(auth[key], ['authorization', key]);
+    string(auth.reason, ['authorization', 'reason']);
+  }
+  const measured = evidence(root.evidence, 'timestamp', ['evidence']);
+  if (measured.status === 'known') {
+    const timestamp = measured.timestamp;
+    const valid = typeof timestamp === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(timestamp) &&
+      Number.isFinite(Date.parse(timestamp)) && new Date(timestamp).toISOString() === timestamp;
+    relation(valid, ['evidence', 'timestamp'], 'Expected an actual UTC timestamp with millisecond precision');
+  }
+  return issues.length ? { success: false, error: { issues } } : { success: true, data: value, diagnostics };
+}
+
+/** Versioned schema facade; syntax success grants no runtime approval. */
+export const roleProfileEvidenceSchema = Object.freeze({ safeParse });

package/scripts/lib/scope-gate.mjs

@@ -5,14 +5,15 @@
  * hot-paths — all sync. Re-exported by hardening.mjs as a barrel so existing
  * importers keep working unchanged.
  *
- * Layering: hook-safe — pure functions only; no I/O at import time;
- * ESM-pure for fast hook hot-paths. Hooks (under `hooks/`) import from
- * this lib; this lib MUST NOT reverse-import from `hooks/`. Cross-cutting
- * invariant for all exports below — see #554 A2.
+ * Layering: hook-safe synchronous helpers; no I/O at import time. Guard
+ * context lookups read bounded filesystem state when called. Hooks (under
+ * `hooks/`) import this ESM-only lib; it MUST NOT reverse-import from hooks.
+ * Cross-cutting invariant for all exports below — see #554 A2.
  */
 
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, lstatSync, openSync, fstatSync, readSync, closeSync, constants } from 'node:fs';
 import path from 'node:path';
+import { resolveSessionRoot, isolatedAgentCheckout, registeredWorktreeRoots } from './platform.mjs';
 
 import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './command-blocker.mjs';
 
@@ -106,6 +107,68 @@ export function findOwnScopeFile(projectRoot, ownIds, classify) {
   return { path: null, foreignPath };
 }
 
+/**
+ * Guard context: control state belongs to the coordinator, relative grants to
+ * the actual isolated checkout. Remote adoption requires unique OWN identity;
+ * local unknown/corrupt/foreign/missing dispositions remain unchanged.
+ * Root-only discovery deliberately excludes arbitrary worktree subdirectories;
+ * revisit when the harness supplies a coordinator-root witness (#1504).
+ * @param {{cwd: string, ownIds: Set<string>, classify: Function}} options
+ * @returns {{manifestRoot: string, writeRoot: string, path: string|null,
+ *   foreignPath: string|null, isolated: boolean, error: string|null}}
+ */
+export function resolveScopeContext({ cwd, ownIds, classify }) {
+  let manifestRoot = resolveSessionRoot(cwd);
+  try { manifestRoot = realpathSync.native(manifestRoot); } catch { /* preserve non-existing-root fallback */ }
+  const local = findOwnScopeFile(manifestRoot, ownIds, classify);
+  const agent = isolatedAgentCheckout(cwd);
+  const context = { manifestRoot, writeRoot: agent?.writeRoot ?? manifestRoot,
+    ...local, isolated: agent !== null, error: null };
+  if (!agent || local.path || ownIds.size === 0) return context;
+  const candidates = registeredWorktreeRoots(agent.commonDir);
+  if (candidates.error) return { ...context, error: candidates.error };
+  const matches = new Map();
+  for (const root of candidates.roots) {
+    if (root === agent.writeRoot || root === manifestRoot || isolatedAgentCheckout(root)) continue;
+    // Inspect precedence candidates separately. An unsafe candidate has unknown
+    // ownership: it must never turn an isolated session into a no-scope ALLOW.
+    for (const dir of SCOPE_FILE_DIRS) {
+      const file = path.join(root, dir, 'wave-scope.json');
+      let fd;
+      let raw;
+      try {
+        const before = lstatSync(file);
+        if (!before.isFile() || before.size > 1024 * 1024) return { ...context, error: 'unsafe-coordinator-scope' };
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const opened = fstatSync(fd);
+        if (!opened.isFile() || opened.ino !== before.ino || opened.dev !== before.dev || opened.size > 1024 * 1024) return { ...context, error: 'unsafe-coordinator-scope' };
+        const buffer = Buffer.alloc(1024 * 1024 + 1);
+        let length = 0;
+        while (length < buffer.length) {
+          const n = readSync(fd, buffer, length, buffer.length - length, null);
+          if (n === 0) break;
+          length += n;
+        }
+        if (length > 1024 * 1024) return { ...context, error: 'unsafe-coordinator-scope' };
+        raw = buffer.toString('utf8', 0, length);
+      } catch (err) {
+        if (err?.code === 'ENOENT') continue;
+        return { ...context, error: 'unsafe-coordinator-scope' };
+      } finally { if (fd !== undefined) closeSync(fd); }
+      try {
+        const scope = JSON.parse(raw);
+        if (classify(scope, ownIds).verdict === 'own') {
+          matches.set(realpathSync(file), { root, path: file, foreignPath: null });
+          break; // highest-precedence positively owned manifest in this root
+        }
+      } catch { /* unbound/corrupt remote state is never authority */ }
+    }
+  }
+  if (matches.size > 1) return { ...context, error: 'ambiguous-coordinator-scope' };
+  const match = matches.values().next().value;
+  return match ? { ...context, manifestRoot: match.root, path: match.path, foreignPath: null } : context;
+}
+
 /**
  * Read the enforcement level from a scope file.
  * Defaults to "strict" (fail-closed) on parse error or missing field.

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',