chati-dev 4.5.16 → 4.5.28

package/src/orchestrator/session-manager.js

@@ -6,36 +6,391 @@
  */
 
 import * as yaml from 'js-yaml';
-import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
-import { join, dirname, resolve } from 'path';
-import lockfile from 'proper-lockfile';
+import {
+  closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync,
+  openSync, readSync, realpathSync, renameSync, rmSync, rmdirSync,
+  unlinkSync, writeFileSync, readFileSync,
+} from 'fs';
+import { basename, join, dirname, resolve } from 'path';
+import { randomUUID } from 'crypto';
+import { hostname } from 'node:os';
 
 const SESSION_FILE = '.chati/session.yaml';
+const SESSION_MAX_BYTES = 4 * 1024 * 1024;
+const SESSION_LOCK_OWNER_MAX_BYTES = 16 * 1024;
+const SESSION_LOCK_STALE_AFTER_MS = 30_000;
+const SESSION_TEST_HOOKS = Symbol.for('chati.session-manager.security-test-hooks');
+const UNSAFE_SESSION_LOCK_OWNER = Symbol('unsafe-session-lock-owner');
+
+function assertSessionWritableSize(value) {
+  if (Buffer.byteLength(JSON.stringify(value)) > SESSION_MAX_BYTES) {
+    throw new Error('session.yaml exceeds the 4 MiB safety limit');
+  }
+}
+
+function runSecurityTestHook(name, detail) {
+  const hook = globalThis[SESSION_TEST_HOOKS]?.[name];
+  if (typeof hook === 'function') hook(detail);
+}
+
+function sameFileIdentity(left, right) {
+  return Boolean(left && right && left.dev === right.dev && left.ino === right.ino);
+}
+
+function sameFileSnapshot(left, right) {
+  return sameFileIdentity(left, right)
+    && left.mode === right.mode
+    && left.uid === right.uid
+    && left.gid === right.gid
+    && left.nlink === right.nlink
+    && left.size === right.size
+    && left.mtimeMs === right.mtimeMs
+    && left.ctimeMs === right.ctimeMs;
+}
+
+function sameLockOwnerSnapshot(left, right) {
+  return sameFileIdentity(left, right)
+    && left.mode === right.mode
+    && left.uid === right.uid
+    && left.gid === right.gid
+    && left.nlink === right.nlink
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs;
+}
+
+function openDirectoryNoFollow(directoryPath) {
+  const fd = openSync(
+    directoryPath,
+    constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0),
+  );
+  const stat = fstatSync(fd);
+  if (!stat.isDirectory()) {
+    closeSync(fd);
+    throw new Error('The .chati path must be a real directory');
+  }
+  return { fd, stat };
+}
+
+function assertDirectoryIdentity(directoryPath, expected) {
+  let opened;
+  try {
+    opened = openDirectoryNoFollow(directoryPath);
+    if (!sameFileIdentity(opened.stat, expected)) {
+      throw new Error('The .chati directory changed during the session operation');
+    }
+  } finally {
+    if (opened) closeSync(opened.fd);
+  }
+}
+
+function openRegularFileNoFollow(path, { allowMissing = false } = {}) {
+  let fd;
+  try {
+    fd = openSync(
+      path,
+      constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0),
+    );
+  } catch (err) {
+    if (allowMissing && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1) throw new Error('session.yaml must be a regular file');
+    if (stat.size > SESSION_MAX_BYTES) throw new Error('session.yaml exceeds the 4 MiB safety limit');
+    return { fd, stat };
+  } catch (err) {
+    closeSync(fd);
+    throw err;
+  }
+}
+
+function assertPathIdentity(path, expected, { allowMissing = false } = {}) {
+  const opened = openRegularFileNoFollow(path, { allowMissing });
+  if (!opened) {
+    if (expected !== null) throw new Error('session.yaml changed during the session operation');
+    return;
+  }
+  try {
+    if (expected === null || !sameFileSnapshot(opened.stat, expected)) {
+      throw new Error('session.yaml changed during the session operation');
+    }
+  } finally {
+    closeSync(opened.fd);
+  }
+}
+
+function readRegularFileBounded(opened) {
+  const buffer = Buffer.allocUnsafe(SESSION_MAX_BYTES + 1);
+  let offset = 0;
+  while (offset < buffer.length) {
+    const bytesRead = readSync(opened.fd, buffer, offset, buffer.length - offset, null);
+    if (bytesRead === 0) break;
+    offset += bytesRead;
+  }
+  if (offset > SESSION_MAX_BYTES) throw new Error('session.yaml exceeds the 4 MiB safety limit');
+  return buffer.subarray(0, offset).toString('utf8');
+}
 
 /**
- * Atomic write helper. Writes `content` to a sibling `.tmp` file and then
- * renames it into place. If the process is killed mid-write the original
- * remains intact. Same-FS rename on POSIX is atomic; on Windows it's
- * best-effort. Mirrors the pattern used by `chati.dev/hooks/prism-engine.js`
- * `writeBackSession` to keep both hook and CLI write paths consistent.
+ * Atomic write helper. On Linux, all destination operations use the pinned
+ * directory descriptor through /proc/self/fd so an ancestor replacement cannot
+ * redirect the final rename. Other platforms retain the canonical path plus
+ * immediate identity checks before and after the rename.
  */
-function writeFileAtomic(path, content, encoding = 'utf-8') {
-  const tmp = `${path}.tmp`;
-  writeFileSync(tmp, content, encoding);
-  renameSync(tmp, path);
+function writeFileAtomic(path, content, encoding = 'utf-8', {
+  expectedDestinationIdentity,
+  expectedDirectoryIdentity,
+} = {}) {
+  if (Buffer.byteLength(String(content), encoding) > SESSION_MAX_BYTES) {
+    throw new Error('session.yaml exceeds the 4 MiB safety limit');
+  }
+  const directoryPath = dirname(path);
+  let directory;
+  let destination;
+  let tmp;
+  let tmpFd;
+  let tmpIdentity;
+  try {
+    directory = openDirectoryNoFollow(directoryPath);
+    if (expectedDirectoryIdentity && !sameFileIdentity(directory.stat, expectedDirectoryIdentity)) {
+      throw new Error('The .chati directory changed during the session operation');
+    }
+    const directoryReference = process.platform === 'linux'
+      ? `/proc/self/fd/${directory.fd}`
+      : directoryPath;
+    destination = join(directoryReference, basename(path));
+    tmp = join(directoryReference, `${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    const expectedDestination = expectedDestinationIdentity === undefined
+      ? (() => {
+          const opened = openRegularFileNoFollow(destination, { allowMissing: true });
+          if (!opened) return null;
+          try { return opened.stat; } finally { closeSync(opened.fd); }
+        })()
+      : expectedDestinationIdentity;
+    tmpFd = openSync(
+      tmp,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0),
+      0o600,
+    );
+    tmpIdentity = fstatSync(tmpFd);
+    if (!tmpIdentity.isFile() || tmpIdentity.nlink !== 1) throw new Error('Session temporary must be a regular file');
+    writeFileSync(tmpFd, content, { encoding });
+    fsyncSync(tmpFd);
+
+    runSecurityTestHook('beforeAtomicRename', { path, tmp });
+    assertDirectoryIdentity(directoryPath, directory.stat);
+    assertPathIdentity(destination, expectedDestination, { allowMissing: true });
+    const currentTmp = lstatSync(tmp);
+    if (currentTmp.isSymbolicLink() || !currentTmp.isFile() || !sameFileIdentity(currentTmp, tmpIdentity)) {
+      throw new Error('Session temporary changed before atomic rename');
+    }
+    runSecurityTestHook('beforeAtomicRenameCommit', { path, tmp });
+    assertDirectoryIdentity(directoryPath, directory.stat);
+    assertPathIdentity(destination, expectedDestination, { allowMissing: true });
+    renameSync(tmp, destination);
+    fsyncSync(directory.fd);
+    assertDirectoryIdentity(directoryPath, directory.stat);
+  } finally {
+    if (tmpFd !== undefined) closeSync(tmpFd);
+    try {
+      const currentTmp = lstatSync(tmp);
+      if (tmpIdentity && currentTmp.isFile() && !currentTmp.isSymbolicLink()
+        && sameFileIdentity(currentTmp, tmpIdentity)) rmSync(tmp, { force: true });
+    } catch { /* leave an unverified temporary untouched */ }
+    if (directory) closeSync(directory.fd);
+  }
+}
+
+function readSessionDocumentRecord(sessionPath) {
+  const directoryPath = dirname(sessionPath);
+  let directory;
+  let opened;
+  try {
+    directory = openDirectoryNoFollow(directoryPath);
+    runSecurityTestHook('beforeReadOpen', { sessionPath });
+    opened = openRegularFileNoFollow(sessionPath);
+    runSecurityTestHook('afterReadOpen', { sessionPath, fd: opened.fd });
+    const raw = readRegularFileBounded(opened);
+    runSecurityTestHook('afterReadContent', { sessionPath, fd: opened.fd });
+    const finalStat = fstatSync(opened.fd);
+    if (!sameFileSnapshot(opened.stat, finalStat)) {
+      throw new Error('session.yaml changed during the session operation');
+    }
+    const session = yaml.load(raw);
+    if (!session || typeof session !== 'object' || Array.isArray(session)) throw new Error('Invalid session document');
+    assertDirectoryIdentity(directoryPath, directory.stat);
+    assertPathIdentity(sessionPath, opened.stat);
+    return { session, identity: opened.stat, directoryIdentity: directory.stat };
+  } finally {
+    if (opened) closeSync(opened.fd);
+    if (directory) closeSync(directory.fd);
+  }
+}
+
+function readSessionDocument(sessionPath) {
+  return readSessionDocumentRecord(sessionPath).session;
+}
+
+function readRuntimeSessionDocument(sessionPath) {
+  let releaseLock = null;
+  try {
+    try {
+      releaseLock = waitForSessionWriteLock(sessionPath);
+    } catch (err) {
+      // A genuinely read-only project cannot create the sibling lock directory
+      // and cannot be mutated by this process. Preserve read-only inspection
+      // while retaining the descriptor and path-identity checks.
+      if (!['EACCES', 'EROFS'].includes(err.code)) throw err;
+    }
+    return readSessionDocument(sessionPath);
+  } finally {
+    if (releaseLock) releaseLock();
+  }
+}
+
+function readSessionDocumentRecordIfPresent(sessionPath) {
+  try {
+    return readSessionDocumentRecord(sessionPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function sessionLockOwner(lockPath) {
+  const ownerPath = join(lockPath, 'owner.json');
+  let descriptor;
+  try {
+    descriptor = openSync(ownerPath, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    const stat = fstatSync(descriptor, { bigint: true });
+    if (!stat.isFile() || stat.nlink !== 1n || stat.size > BigInt(SESSION_LOCK_OWNER_MAX_BYTES)) {
+      return UNSAFE_SESSION_LOCK_OWNER;
+    }
+    runSecurityTestHook('afterSessionLockOwnerStat', { path: ownerPath });
+    const bytes = Buffer.allocUnsafe(SESSION_LOCK_OWNER_MAX_BYTES + 1);
+    let total = 0;
+    while (total < bytes.length) {
+      const bytesRead = readSync(descriptor, bytes, total, bytes.length - total, null);
+      if (bytesRead === 0) break;
+      total += bytesRead;
+    }
+    const after = fstatSync(descriptor, { bigint: true });
+    if (total > SESSION_LOCK_OWNER_MAX_BYTES || !sameLockOwnerSnapshot(stat, after)) {
+      return UNSAFE_SESSION_LOCK_OWNER;
+    }
+    let owner;
+    try { owner = JSON.parse(bytes.subarray(0, total).toString('utf8')); }
+    catch { return null; }
+    return owner && typeof owner.token === 'string' ? owner : null;
+  } catch (error) { return error?.code === 'ENOENT' ? null : UNSAFE_SESSION_LOCK_OWNER; }
+  finally { if (descriptor !== undefined) closeSync(descriptor); }
+}
+
+function localProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+}
+
+function localProcessIdentity(pid) {
+  if (process.platform !== 'linux' || !Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const commandEnd = stat.lastIndexOf(')');
+    if (commandEnd < 0) return null;
+    const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+    const startTime = fields[19]; // field 22; fields[0] is field 3 (state)
+    const bootId = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+    if (!startTime || !bootId) return null;
+    return `linux-proc-v1:${bootId}:${startTime}`;
+  } catch { return null; }
+}
+
+function sessionLockAgeMs(lockStat) {
+  return Math.max(0, Date.now() - lockStat.mtimeMs);
+}
+
+function recoverAbandonedSessionLock(lockPath) {
+  let initial;
+  try { initial = lstatSync(lockPath); } catch (error) { return error?.code === 'ENOENT'; }
+  if (initial.isSymbolicLink() || !initial.isDirectory()) return false;
+  const owner = sessionLockOwner(lockPath);
+  if (owner === UNSAFE_SESSION_LOCK_OWNER) return UNSAFE_SESSION_LOCK_OWNER;
+  const staleByAge = sessionLockAgeMs(initial) >= SESSION_LOCK_STALE_AFTER_MS;
+  if (owner?.hostname && owner.hostname !== hostname() && !staleByAge) return false;
+  if (owner?.hostname === hostname() && localProcessAlive(owner.pid)) {
+    const observedIdentity = localProcessIdentity(owner.pid);
+    if (owner.process_identity && observedIdentity === owner.process_identity) return false;
+    // Legacy owners and platforms without a stable process start identity get
+    // a bounded lease instead of trusting a potentially recycled PID forever.
+    if ((!owner.process_identity || !observedIdentity) && !staleByAge) return false;
+  }
+  if (!owner && !staleByAge) return false;
+  const electionPath = join(lockPath, 'recovery.json');
+  let electionFd;
+  try {
+    electionFd = openSync(electionPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    writeFileSync(electionFd, JSON.stringify({ pid: process.pid, hostname: hostname(), token: randomUUID() }));
+    fsyncSync(electionFd);
+  } catch {
+    if (electionFd !== undefined) closeSync(electionFd);
+    return false;
+  }
+  const quarantine = `${lockPath}.stale.${process.pid}.${randomUUID()}`;
+  try {
+    const current = lstatSync(lockPath);
+    const currentOwner = sessionLockOwner(lockPath);
+    if (currentOwner === UNSAFE_SESSION_LOCK_OWNER) return UNSAFE_SESSION_LOCK_OWNER;
+    if (!sameFileIdentity(initial, current) || currentOwner?.token !== owner?.token) return false;
+    renameSync(lockPath, quarantine);
+    try { unlinkSync(join(quarantine, 'owner.json')); } catch { /* owner may be absent */ }
+    unlinkSync(join(quarantine, 'recovery.json'));
+    rmdirSync(quarantine);
+    return true;
+  } catch { return false; }
+  finally { if (electionFd !== undefined) closeSync(electionFd); }
 }
 
 function waitForSessionWriteLock(sessionPath, maxWaitMs = 2000) {
   const startedAt = Date.now();
+  const lockPath = `${sessionPath}.lock`;
+  const parentPath = dirname(lockPath);
+  let unsafeLockObserved = false;
   while (true) {
     try {
-      return lockfile.lockSync(sessionPath, {
-        realpath: false,
-        stale: 30_000,
-        update: 10_000,
-      });
+      mkdirSync(lockPath, { mode: 0o700 });
+      const token = randomUUID();
+      const ownerPath = join(lockPath, 'owner.json');
+      const ownerFd = openSync(ownerPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+      try {
+        writeFileSync(ownerFd, JSON.stringify({
+          schema_version: 2,
+          pid: process.pid,
+          hostname: hostname(),
+          process_identity: localProcessIdentity(process.pid),
+          token,
+          acquired_at: new Date().toISOString(),
+        }));
+        fsyncSync(ownerFd);
+      } finally { closeSync(ownerFd); }
+      const lockDirFd = openSync(lockPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+      try { fsyncSync(lockDirFd); } finally { closeSync(lockDirFd); }
+      const parentFd = openSync(parentPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+      try { fsyncSync(parentFd); } finally { closeSync(parentFd); }
+      return () => {
+        const current = sessionLockOwner(lockPath);
+        if (current?.token !== token) return;
+        unlinkSync(ownerPath);
+        rmdirSync(lockPath);
+        const releaseParentFd = openSync(parentPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        try { fsyncSync(releaseParentFd); } finally { closeSync(releaseParentFd); }
+      };
     } catch (err) {
-      if (err.code !== 'ELOCKED') throw err;
+      if (err.code !== 'EEXIST') throw err;
+      const recovery = unsafeLockObserved ? false : recoverAbandonedSessionLock(lockPath);
+      if (recovery === UNSAFE_SESSION_LOCK_OWNER) unsafeLockObserved = true;
+      else if (recovery) continue;
       if (Date.now() - startedAt >= maxWaitMs) {
         throw new Error(`Timed out waiting for session write lock after ${maxWaitMs}ms`, { cause: err });
       }
@@ -47,17 +402,161 @@ function waitForSessionWriteLock(sessionPath, maxWaitMs = 2000) {
 function findSessionProjectDir(startDir) {
   let current = resolve(startDir);
   while (true) {
-    if (existsSync(join(current, SESSION_FILE))) return current;
+    const chatiDir = join(current, '.chati');
+    if (existsSync(chatiDir) && !lstatSync(chatiDir).isSymbolicLink() && lstatSync(chatiDir).isDirectory()
+      && existsSync(join(current, SESSION_FILE))
+      && !lstatSync(join(current, SESSION_FILE)).isSymbolicLink()
+      && lstatSync(join(current, SESSION_FILE)).isFile()) return current;
     const parent = dirname(current);
     if (parent === current) return null;
     current = parent;
   }
 }
 
+function validateSessionPath(projectDir, { createDirectory = false, requireFile = false } = {}) {
+  const projectRoot = realpathSync(resolve(projectDir));
+  const requestedSessionPath = join(projectRoot, SESSION_FILE);
+  const sessionDir = dirname(requestedSessionPath);
+  let dirStat = null;
+  try {
+    dirStat = lstatSync(sessionDir);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  if (dirStat) {
+    if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) {
+      throw new Error('The .chati path must be a real directory');
+    }
+  } else if (createDirectory) {
+    mkdirSync(sessionDir, { recursive: true });
+  } else {
+    throw new Error('Session directory not found');
+  }
+  const realSessionDir = realpathSync(sessionDir);
+  if (dirname(realSessionDir) !== projectRoot || realSessionDir !== join(projectRoot, '.chati')) {
+    throw new Error('The .chati directory must remain inside the project');
+  }
+  const openedDirectory = openDirectoryNoFollow(sessionDir);
+  closeSync(openedDirectory.fd);
+  const sessionPath = join(realSessionDir, 'session.yaml');
+  let fileStat = null;
+  try {
+    fileStat = lstatSync(sessionPath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  if (fileStat) {
+    if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
+      throw new Error('session.yaml must be a regular file');
+    }
+  } else if (requireFile) {
+    throw new Error('Session file not found');
+  }
+  return sessionPath;
+}
+
+/**
+ * Read canonical session state without migration or write-back. Authorization
+ * and routing consumers use this surface so invalid, symlinked, oversized or
+ * non-regular session files fail closed under the same checks as mutations.
+ */
+export function readSessionSafe(projectDir) {
+  let sessionPath;
+  let releaseLock = null;
+  try {
+    sessionPath = validateSessionPath(projectDir, { requireFile: true });
+    // Security consumers read under the same lock used by atomic writers. This
+    // avoids false failures during a legitimate rename without retrying an
+    // attacker-controlled replacement after an identity check has failed.
+    releaseLock = waitForSessionWriteLock(sessionPath);
+    const record = readSessionDocumentRecord(sessionPath);
+    releaseLock();
+    releaseLock = null;
+    return { loaded: true, missing: false, session: record.session, path: sessionPath, error: null };
+  } catch (err) {
+    const missing = err.code === 'ENOENT'
+      || err.message === 'Session directory not found'
+      || err.message === 'Session file not found';
+    return {
+      loaded: false,
+      missing,
+      session: null,
+      path: sessionPath || join(resolve(projectDir), SESSION_FILE),
+      error: err.message,
+    };
+  } finally {
+    if (releaseLock) {
+      try { releaseLock(); } catch { /* the read already fails closed above */ }
+    }
+  }
+}
+
+/**
+ * Persist the installer-generated initial document through the same lock and
+ * atomic writer used by the runtime. Existing session state is always
+ * preserved, including an inactive pre-init session created by an earlier
+ * installation.
+ */
+export function initializeSessionDocument(projectDir, yamlContent) {
+  let sessionPath;
+  let releaseLock = null;
+  let outcome;
+  try {
+    const parsed = yaml.load(yamlContent);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('Invalid initial session document');
+    }
+    sessionPath = validateSessionPath(projectDir, { createDirectory: true });
+    releaseLock = waitForSessionWriteLock(sessionPath);
+    const existing = readSessionDocumentRecordIfPresent(sessionPath);
+    if (existing) {
+      outcome = { created: false, preserved: true, session: existing.session, path: sessionPath };
+    } else {
+      const directory = openDirectoryNoFollow(dirname(sessionPath));
+      try {
+        writeFileAtomic(sessionPath, yamlContent, 'utf-8', {
+          expectedDestinationIdentity: null,
+          expectedDirectoryIdentity: directory.stat,
+        });
+      } finally {
+        closeSync(directory.fd);
+      }
+      outcome = { created: true, preserved: false, session: parsed, path: sessionPath };
+    }
+  } catch (err) {
+    outcome = {
+      created: false,
+      preserved: false,
+      session: null,
+      path: sessionPath || join(projectDir, SESSION_FILE),
+      error: `Failed to initialize session document: ${err.message}`,
+    };
+  } finally {
+    if (releaseLock) {
+      try {
+        releaseLock();
+      } catch (err) {
+        outcome = {
+          created: false,
+          preserved: false,
+          session: null,
+          path: sessionPath,
+          error: `Session initialization lock was compromised: ${err.message}`,
+        };
+      }
+    }
+  }
+  return outcome;
+}
+
 /**
  * Default session template.
  */
 const CURRENT_SCHEMA_VERSION = '1.2';
+const V2_SESSION_AGENTS = new Set([
+  'greenfield-wu', 'brownfield-wu', 'brief', 'detail', 'architect', 'ux',
+  'qa-planning', 'phases', 'tasks',
+]);
 
 const DEFAULT_SESSION = {
   schema_version: CURRENT_SCHEMA_VERSION,
@@ -162,15 +661,22 @@ const DEFAULT_SESSION = {
  * @returns {{ created: boolean, session: object, path: string }}
  */
 export function initSession(projectDir, options = {}) {
-  const sessionPath = join(projectDir, SESSION_FILE);
-  const dir = dirname(sessionPath);
-
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
+  let sessionPath;
+  try {
+    sessionPath = validateSessionPath(projectDir, { createDirectory: true });
+  } catch (err) {
+    return { created: false, session: null, path: join(projectDir, SESSION_FILE), error: err.message };
   }
 
+  const sessionAgents = Object.fromEntries(
+    Object.entries(DEFAULT_SESSION.agents)
+      .filter(([agent]) => options.runtimeVersion !== 2 || V2_SESSION_AGENTS.has(agent))
+      .map(([agent, state]) => [agent, { ...state }]),
+  );
   const session = {
     ...DEFAULT_SESSION,
+    runtime_version: options.runtimeVersion === 2 ? 2 : 1,
+    agents: sessionAgents,
     mode: options.mode || 'discover',
     project: {
       name: options.projectName || '',
@@ -185,27 +691,69 @@ export function initSession(projectDir, options = {}) {
     providers_enabled: options.providersEnabled || [],
   };
 
+  let releaseLock = null;
+  let outcome;
   try {
-    const yamlContent = yaml.dump(session, {
-      lineWidth: -1,
-      noRefs: true,
-    });
-
-    writeFileAtomic(sessionPath, yamlContent);
-
-    return {
-      created: true,
-      session,
-      path: sessionPath,
-    };
+    releaseLock = waitForSessionWriteLock(sessionPath);
+    const existingRecord = readSessionDocumentRecordIfPresent(sessionPath);
+    if (existingRecord) {
+      const existing = existingRecord.session;
+      const hasConcurrentProgress = existing && typeof existing === 'object' && !Array.isArray(existing) && (
+        existing.pending_interaction
+        || (Array.isArray(existing.completed_agents) && existing.completed_agents.length > 0)
+        || (existing.mode && existing.mode !== 'discover')
+        || (existing.current_agent && existing.current_agent !== '')
+      );
+      if (hasConcurrentProgress) {
+        outcome = {
+          created: true,
+          preserved: true,
+          session: existing,
+          path: sessionPath,
+        };
+      } else {
+        const yamlContent = yaml.dump(session, { lineWidth: -1, noRefs: true });
+        writeFileAtomic(sessionPath, yamlContent, 'utf-8', {
+          expectedDestinationIdentity: existingRecord.identity,
+          expectedDirectoryIdentity: existingRecord.directoryIdentity,
+        });
+        outcome = { created: true, session, path: sessionPath };
+      }
+    } else {
+      const yamlContent = yaml.dump(session, { lineWidth: -1, noRefs: true });
+      const directory = openDirectoryNoFollow(dirname(sessionPath));
+      try {
+        writeFileAtomic(sessionPath, yamlContent, 'utf-8', {
+          expectedDestinationIdentity: null,
+          expectedDirectoryIdentity: directory.stat,
+        });
+      } finally {
+        closeSync(directory.fd);
+      }
+      outcome = { created: true, session, path: sessionPath };
+    }
   } catch (err) {
-    return {
+    outcome = {
       created: false,
       session: null,
       path: sessionPath,
       error: `Failed to create session: ${err.message}`,
     };
+  } finally {
+    if (releaseLock) {
+      try {
+        releaseLock();
+      } catch (err) {
+        outcome = {
+          created: false,
+          session: null,
+          path: sessionPath,
+          error: `Session initialization lock was compromised: ${err.message}`,
+        };
+      }
+    }
   }
+  return outcome;
 }
 
 /**
@@ -378,19 +926,21 @@ function inferLegacyProvider(model) {
  * @returns {{ loaded: boolean, session: object|null, error: string|null, migrated?: boolean }}
  */
 export function loadSession(projectDir) {
-  const sessionPath = join(projectDir, SESSION_FILE);
-
-  if (!existsSync(sessionPath)) {
+  let sessionPath;
+  try {
+    sessionPath = validateSessionPath(projectDir, { requireFile: true });
+  } catch (err) {
     return {
       loaded: false,
       session: null,
-      error: 'Session file not found',
+      error: err.message,
     };
   }
-
   try {
-    const content = readFileSync(sessionPath, 'utf-8');
-    let session = yaml.load(content);
+    // Canonical runtime reads participate in the same cross-process lock as
+    // atomic writers. Retrying unlocked reads can exhaust every attempt while
+    // another process replaces session.yaml under scheduler pressure.
+    let session = readRuntimeSessionDocument(sessionPath);
 
     // Run migration if needed
     const migration = migrateSession(session);
@@ -458,21 +1008,221 @@ export function updateSession(projectDir, updates) {
   });
 }
 
+/**
+ * Atomically transition conversation ownership and lifecycle state. Returning
+ * the prior values lets callers record timeline evidence without performing a
+ * race-prone read before the canonical mutation.
+ */
+export function transitionSessionLifecycle(projectDir, {
+  activeHarness,
+  sessionStatus,
+} = {}) {
+  let previous = null;
+  const persisted = mutateSession(projectDir, (session) => {
+    previous = {
+      active_harness: session.active_harness || null,
+      session_status: session.session_status || 'inactive',
+      current_agent: session.current_agent || '',
+      mode: session.mode || 'discover',
+      execution_mode: session.execution_mode || 'interactive',
+      language: session.language || 'en',
+    };
+    if (activeHarness !== undefined) session.active_harness = activeHarness;
+    if (sessionStatus !== undefined) session.session_status = sessionStatus;
+    return session;
+  });
+  return { ...persisted, previous };
+}
+
+/** Restore a lifecycle transition only while it still owns the canonical state. */
+export function rollbackSessionLifecycle(projectDir, {
+  expectedActiveHarness,
+  expectedSessionStatus,
+  previous,
+} = {}) {
+  let outcome = { rolledBack: false };
+  const persisted = mutateSession(projectDir, (session) => {
+    const activeHarness = session.active_harness || null;
+    const sessionStatus = session.session_status || 'inactive';
+    if (activeHarness !== expectedActiveHarness || sessionStatus !== expectedSessionStatus) {
+      outcome = {
+        rolledBack: false,
+        code: 'SESSION_ROLLBACK_CONFLICT',
+        error: 'Canonical lifecycle changed before projection rollback.',
+      };
+      return session;
+    }
+    session.active_harness = previous?.active_harness ?? null;
+    session.session_status = previous?.session_status || 'inactive';
+    outcome = { rolledBack: true };
+    return session;
+  });
+  return { ...persisted, ...outcome };
+}
+
+function cloneSessionValue(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function snapshotAgentDispatch(session, agentNames) {
+  return {
+    current_agent: session.current_agent || '',
+    has_current_execution_binding: Object.hasOwn(session, 'current_execution_binding'),
+    current_execution_binding: cloneSessionValue(session.current_execution_binding),
+    agents: Object.fromEntries(agentNames.map((agent) => [agent, {
+      present: Object.hasOwn(session.agents || {}, agent),
+      value: cloneSessionValue(session.agents?.[agent]),
+    }])),
+  };
+}
+
+/** Atomically mark a legacy execution active while retaining exact rollback state. */
+export function activateAgentExecutionState(projectDir, {
+  agent,
+  binding,
+  markInProgress = true,
+} = {}) {
+  if (!agent) return { saved: false, activated: false, error: 'Agent activation requires an agent' };
+  let previous = null;
+  const persisted = mutateSession(projectDir, (session) => {
+    session.agents = session.agents || {};
+    previous = snapshotAgentDispatch(session, [agent]);
+    session.current_agent = agent;
+    if (binding) session.current_execution_binding = cloneSessionValue(binding);
+    if (markInProgress) {
+      session.agents[agent] = {
+        ...(session.agents[agent] || {}),
+        status: 'in_progress',
+      };
+    }
+    return session;
+  });
+  return { ...persisted, activated: persisted.saved, previous };
+}
+
+/**
+ * Roll back an agent dispatch only if every exact execution identity still
+ * owns the canonical state. This prevents compensation from erasing a newer
+ * CLI's successful mutation.
+ */
+export function rollbackAgentDispatch(projectDir, {
+  expectedAgent,
+  claims = null,
+  previous,
+} = {}) {
+  let outcome = { rolledBack: false };
+  const persisted = mutateSession(projectDir, (session) => {
+    if (!previous || session.current_agent !== expectedAgent) {
+      outcome = {
+        rolledBack: false,
+        code: 'SESSION_ROLLBACK_CONFLICT',
+        error: 'Canonical agent state changed before projection rollback.',
+      };
+      return session;
+    }
+    if (claims) {
+      for (const [agent, claimId] of Object.entries(claims)) {
+        if (!claimId || session.agents?.[agent]?.execution_claim_id !== claimId) {
+          outcome = {
+            rolledBack: false,
+            code: 'SESSION_ROLLBACK_CONFLICT',
+            error: `Execution claim for ${agent} changed before projection rollback.`,
+          };
+          return session;
+        }
+      }
+    } else if (session.agents?.[expectedAgent]?.status !== 'in_progress'
+      && previous.agents?.[expectedAgent]?.value?.status !== session.agents?.[expectedAgent]?.status) {
+      outcome = {
+        rolledBack: false,
+        code: 'SESSION_ROLLBACK_CONFLICT',
+        error: `Agent ${expectedAgent} changed before projection rollback.`,
+      };
+      return session;
+    }
+
+    session.current_agent = previous.current_agent;
+    if (previous.has_current_execution_binding) {
+      session.current_execution_binding = cloneSessionValue(previous.current_execution_binding);
+    } else {
+      delete session.current_execution_binding;
+    }
+    session.agents = session.agents || {};
+    for (const [agent, snapshot] of Object.entries(previous.agents || {})) {
+      if (snapshot.present) session.agents[agent] = cloneSessionValue(snapshot.value);
+      else delete session.agents[agent];
+    }
+    outcome = { rolledBack: true };
+    return session;
+  });
+  return { ...persisted, ...outcome };
+}
+
+export function updateContextUsage(projectDir, {
+  delta = 0,
+  contextWindowTokens,
+  detectedModel = null,
+  routedProvider = null,
+} = {}) {
+  const normalizedDelta = Math.max(0, Number.isFinite(Number(delta)) ? Math.trunc(Number(delta)) : 0);
+  const normalizedWindow = Math.max(1, Number.isFinite(Number(contextWindowTokens))
+    ? Math.trunc(Number(contextWindowTokens))
+    : 200_000);
+  const persisted = mutateSession(projectDir, (session) => {
+    const current = Math.max(0, Number.isFinite(Number(session.context_tokens_used))
+      ? Math.trunc(Number(session.context_tokens_used))
+      : 0);
+    const tokensUsed = Math.min(normalizedWindow, current + normalizedDelta);
+    const remainingPercent = Math.max(0, Math.round((1 - tokensUsed / normalizedWindow) * 100));
+    const bracket = remainingPercent < 25
+      ? 'CRITICAL'
+      : remainingPercent < 40
+        ? 'DEPLETED'
+        : remainingPercent < 60
+          ? 'MODERATE'
+          : 'FRESH';
+    session.context_tokens_used = tokensUsed;
+    session.context_window_tokens = normalizedWindow;
+    session.context_last_bracket = bracket;
+    if (detectedModel && (session.current_execution_binding?.model || !session.active_model)) {
+      session.active_model = detectedModel;
+    }
+    if (routedProvider) session.active_provider = routedProvider;
+    if ((detectedModel || session.active_model) && !session.model_at_last_audit) {
+      session.model_at_last_audit = detectedModel || session.active_model;
+    }
+    return session;
+  });
+  if (!persisted.saved) return persisted;
+  return {
+    ...persisted,
+    tokensUsed: persisted.session.context_tokens_used,
+    contextWindowTokens: persisted.session.context_window_tokens,
+    bracket: persisted.session.context_last_bracket,
+  };
+}
+
 function mutateSession(projectDir, mutator) {
-  const sessionPath = join(projectDir, SESSION_FILE);
-  if (!existsSync(sessionPath)) return { saved: false, error: 'Session file not found' };
+  let sessionPath;
+  try {
+    sessionPath = validateSessionPath(projectDir, { requireFile: true });
+  } catch (err) {
+    return { saved: false, error: err.message };
+  }
   let releaseLock = null;
   let outcome;
   try {
     releaseLock = waitForSessionWriteLock(sessionPath);
-    const session = yaml.load(readFileSync(sessionPath, 'utf-8'));
-    if (!session || typeof session !== 'object' || Array.isArray(session)) {
-      throw new Error('Invalid session document');
-    }
+    const record = readSessionDocumentRecord(sessionPath);
+    const session = record.session;
     migrateSession(session);
     const nextSession = mutator(session) || session;
+    assertSessionWritableSize(nextSession);
     const yamlContent = yaml.dump(nextSession, { lineWidth: -1, noRefs: true });
-    writeFileAtomic(sessionPath, yamlContent);
+    writeFileAtomic(sessionPath, yamlContent, 'utf-8', {
+      expectedDestinationIdentity: record.identity,
+      expectedDirectoryIdentity: record.directoryIdentity,
+    });
     outcome = { saved: true, session: nextSession };
   } catch (err) {
     outcome = { saved: false, error: `Failed to update session: ${err.message}` };
@@ -488,6 +1238,38 @@ function mutateSession(projectDir, mutator) {
   return outcome;
 }
 
+/**
+ * Runs a projection against the latest canonical session while holding the
+ * same cross-process lock used by mutations. The callback may update derived
+ * harness files, but cannot replace session.yaml itself.
+ */
+export function withSessionProjectionLock(projectDir, projector) {
+  if (typeof projector !== 'function') return { projected: false, error: 'Session projector must be a function' };
+  let sessionPath;
+  try {
+    sessionPath = validateSessionPath(projectDir, { requireFile: true });
+  } catch (err) {
+    return { projected: false, error: err.message, ...(err.code ? { code: err.code } : {}) };
+  }
+  let releaseLock = null;
+  let outcome;
+  try {
+    releaseLock = waitForSessionWriteLock(sessionPath);
+    const session = readSessionDocumentRecord(sessionPath).session;
+    migrateSession(session);
+    outcome = { projected: true, session, result: projector(session) };
+  } catch (err) {
+    outcome = { projected: false, error: `Failed to project session: ${err.message}`, ...(err.code ? { code: err.code } : {}) };
+  } finally {
+    if (releaseLock) {
+      try { releaseLock(); } catch (err) {
+        outcome = { projected: false, error: `Session projection lock was compromised: ${err.message}` };
+      }
+    }
+  }
+  return outcome;
+}
+
 /**
  * Append the exact provider/model binding used for an execution.
  * A short cross-process lock prevents parallel agents from overwriting each
@@ -532,21 +1314,32 @@ export function recordPendingInteraction(projectDir, interaction) {
       catalog_snapshot_ref: interaction.catalogSnapshotRef || null,
     };
     const sameRelay = previous?.agent === interaction.agent && previous?.task_id === taskId;
+    const relayAdvanced = sameRelay && interaction.advanceRelay === true;
+    const interactionId = (!sameRelay || relayAdvanced || !previous?.interaction_id)
+      ? randomUUID()
+      : previous.interaction_id;
     const now = interaction.timestamp || new Date().toISOString();
     session.current_agent = interaction.agent;
     session.current_execution_binding = binding;
     session.agents = session.agents || {};
+    const existingAgent = session.agents[interaction.agent] || {};
     session.agents[interaction.agent] = {
-      ...(session.agents[interaction.agent] || {}),
+      ...existingAgent,
       status: 'waiting_for_user',
+      interaction_id: interactionId,
     };
+    delete session.agents[interaction.agent].execution_claim_id;
+    delete session.agents[interaction.agent].execution_claim_state;
+    delete session.agents[interaction.agent].execution_claim_started_at;
+    delete session.agents[interaction.agent].execution_claim_expires_at;
     session.pending_interaction = {
+      interaction_id: interactionId,
       status: 'waiting_for_user',
       agent: interaction.agent,
       task_id: taskId,
       language: session.language || 'en',
       question: interaction.question,
-      relay_cycles: sameRelay ? (previous.relay_cycles || 1) + 1 : 1,
+      relay_cycles: relayAdvanced ? (previous.relay_cycles || 1) + 1 : (sameRelay ? (previous.relay_cycles || 1) : 1),
       execution_binding: binding,
       created_at: sameRelay ? previous.created_at : now,
       updated_at: now,
@@ -555,6 +1348,319 @@ export function recordPendingInteraction(projectDir, interaction) {
   });
 }
 
+/** Atomically reserve one or more agent executions before returning commands. */
+export function claimAgentExecutions(projectDir, executions = [], claim = {}) {
+  const sessionProjectDir = findSessionProjectDir(projectDir);
+  if (!sessionProjectDir) return { saved: false, claimed: false, error: 'Session file not found in working directory or its parents' };
+  const requested = executions.filter((entry) => entry?.agent);
+  if (requested.length === 0) return { saved: true, claimed: false, claims: {} };
+  let outcome = { claimed: false, claims: {}, previous: null };
+  const now = claim.timestamp ? new Date(claim.timestamp) : new Date();
+  const leaseMs = Math.max(60_000, Number(claim.leaseMs) || 30 * 60 * 1000);
+  const expiresAt = new Date(now.getTime() + leaseMs).toISOString();
+  const result = mutateSession(sessionProjectDir, (session) => {
+    session.agents = session.agents || {};
+    for (const entry of requested) {
+      const current = session.agents[entry.agent] || {};
+      if (current.status === 'completed' || session.completed_agents?.includes(entry.agent)) {
+        outcome = {
+          claimed: false,
+          code: 'AGENT_ALREADY_COMPLETED',
+          error: `Agent ${entry.agent} is already recorded as completed.`,
+          agent: entry.agent,
+        };
+        return session;
+      }
+      if (current.status === 'waiting_for_user') {
+        outcome = {
+          claimed: false,
+          code: 'AGENT_WAITING_FOR_USER',
+          error: `Agent ${entry.agent} has a pending user interaction.`,
+          agent: entry.agent,
+        };
+        return session;
+      }
+      if (current.status === 'awaiting_advance' || current.execution_claim_state === 'awaiting_advance') {
+        outcome = {
+          claimed: false,
+          code: 'AGENT_AWAITING_ADVANCE',
+          error: `Agent ${entry.agent} finished its routed process and is waiting for canonical advance.`,
+          agent: entry.agent,
+        };
+        return session;
+      }
+      const expiry = Date.parse(current.execution_claim_expires_at || '');
+      const liveClaim = current.status === 'in_progress'
+        && current.execution_claim_id
+        && Number.isFinite(expiry)
+        && expiry > now.getTime();
+      if (liveClaim) {
+        outcome = {
+          claimed: false,
+          code: 'AGENT_EXECUTION_IN_FLIGHT',
+          error: `Agent ${entry.agent} already has an active execution claim.`,
+          agent: entry.agent,
+        };
+        return session;
+      }
+    }
+    outcome.previous = snapshotAgentDispatch(session, requested.map(({ agent }) => agent));
+    for (const entry of requested) {
+      const claimId = randomUUID();
+      session.agents[entry.agent] = {
+        ...(session.agents[entry.agent] || {}),
+        status: 'in_progress',
+        execution_claim_id: claimId,
+        execution_claim_state: 'reserved',
+        execution_claim_started_at: now.toISOString(),
+        execution_claim_expires_at: expiresAt,
+      };
+      outcome.claims[entry.agent] = claimId;
+    }
+    session.current_agent = requested[0].agent;
+    if (requested[0].binding) session.current_execution_binding = requested[0].binding;
+    outcome.claimed = true;
+    return session;
+  });
+  return { ...result, ...outcome };
+}
+
+/** Atomically consume a reserved execution command exactly once. */
+export function startAgentExecution(projectDir, match = {}) {
+  const sessionProjectDir = findSessionProjectDir(projectDir);
+  if (!sessionProjectDir) return { saved: false, started: false, error: 'Session file not found in working directory or its parents' };
+  let outcome = { started: false };
+  const result = mutateSession(sessionProjectDir, (session) => {
+    const agent = session.agents?.[match.agent];
+    const expired = Date.parse(agent?.execution_claim_expires_at || '') <= Date.now();
+    if (!agent || agent.execution_claim_id !== match.claimId || agent.execution_claim_state !== 'reserved' || expired) {
+      outcome = {
+        started: false,
+        code: 'AGENT_EXECUTION_CLAIM_INVALID',
+        error: `Execution claim for ${match.agent || 'unknown'} is missing, stale, or already consumed.`,
+      };
+      return session;
+    }
+    agent.execution_claim_state = 'running';
+    agent.execution_started_at = match.timestamp || new Date().toISOString();
+    outcome = { started: true };
+    return session;
+  });
+  return { ...result, ...outcome };
+}
+
+/** Keep a successful routed result durable until the canonical advance records completion. */
+export function holdAgentExecutionForAdvance(projectDir, match = {}) {
+  const sessionProjectDir = findSessionProjectDir(projectDir);
+  if (!sessionProjectDir) return { saved: false, held: false, error: 'Session file not found in working directory or its parents' };
+  let outcome = { held: false };
+  const result = mutateSession(sessionProjectDir, (session) => {
+    const agent = session.agents?.[match.agent];
+    if (!agent) {
+      outcome = { held: false, code: 'AGENT_EXECUTION_NOT_FOUND', error: `Agent ${match.agent || 'unknown'} is not present in the canonical session.` };
+      return session;
+    }
+    if (match.claimId && agent.execution_claim_id !== match.claimId) {
+      outcome = { held: false, code: 'AGENT_EXECUTION_CLAIM_INVALID', error: `Execution claim for ${match.agent} does not own this result.` };
+      return session;
+    }
+    agent.status = 'awaiting_advance';
+    agent.execution_claim_state = 'awaiting_advance';
+    agent.execution_finished_at = match.timestamp || new Date().toISOString();
+    delete agent.execution_claim_expires_at;
+    delete agent.execution_started_at;
+    outcome = { held: true };
+    return session;
+  });
+  return { ...result, ...outcome };
+}
+
+/** Release an exact execution claim after completion or controlled failure. */
+export function releaseAgentExecution(projectDir, match = {}) {
+  const sessionProjectDir = findSessionProjectDir(projectDir);
+  if (!sessionProjectDir) return { saved: false, released: false, error: 'Session file not found in working directory or its parents' };
+  let released = false;
+  const result = mutateSession(sessionProjectDir, (session) => {
+    const agent = session.agents?.[match.agent];
+    if (!agent || agent.execution_claim_id !== match.claimId) return session;
+    if (agent.execution_claim_state === 'awaiting_advance' || agent.status === 'awaiting_advance') return session;
+    if (agent.status === 'in_progress') agent.status = 'pending';
+    delete agent.execution_claim_id;
+    delete agent.execution_claim_state;
+    delete agent.execution_claim_started_at;
+    delete agent.execution_claim_expires_at;
+    delete agent.execution_started_at;
+    released = true;
+    return session;
+  });
+  return { ...result, released };
+}
+
+/** Cancel commands that were reserved but never started when a session exits. */
+export function releaseReservedAgentExecutions(projectDir) {
+  const sessionProjectDir = findSessionProjectDir(projectDir);
+  if (!sessionProjectDir) return { saved: false, released: 0, error: 'Session file not found in working directory or its parents' };
+  let released = 0;
+  const result = mutateSession(sessionProjectDir, (session) => {
+    for (const agent of Object.values(session.agents || {})) {
+      if (agent.execution_claim_state !== 'reserved') continue;
+      if (agent.status === 'in_progress') agent.status = 'pending';
+      delete agent.execution_claim_id;
+      delete agent.execution_claim_state;
+      delete agent.execution_claim_started_at;
+      delete agent.execution_claim_expires_at;
+      released += 1;
+    }
+    return session;
+  });
+  return { ...result, released };
+}
+
+/** Add an identity to pending interactions created by older runtime versions. */
+export function ensurePendingInteractionIdentity(projectDir, fallbackBinding = null) {
+  const sessionProjectDir = findSessionProjectDir(projectDir);
+  if (!sessionProjectDir) return { saved: false, error: 'Session file not found in working directory or its parents' };
+  let interactionId = null;
+  const result = mutateSession(sessionProjectDir, (session) => {
+    if (!session.pending_interaction) return session;
+    const existingId = session.pending_interaction.interaction_id;
+    interactionId = isSafeInteractionId(existingId) ? existingId : randomUUID();
+    session.pending_interaction.interaction_id = interactionId;
+    if (!session.pending_interaction.execution_binding && fallbackBinding) {
+      session.pending_interaction.execution_binding = {
+        provider: fallbackBinding.provider || null,
+        provider_id: fallbackBinding.provider_id || null,
+        model: fallbackBinding.model || null,
+        reasoning_configuration: fallbackBinding.reasoning_configuration || null,
+        catalog_snapshot_ref: fallbackBinding.catalog_snapshot_ref || null,
+      };
+    }
+    return session;
+  });
+  return { ...result, interactionId };
+}
+
+/** Restrict interaction identities to path-inert tokens before file derivation. */
+export function isSafeInteractionId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+}
+
+/** Atomically reserve a pending relay before any provider process is started. */
+export function claimPendingInteraction(projectDir, claim = {}) {
+  const sessionProjectDir = findSessionProjectDir(projectDir);
+  if (!sessionProjectDir) return { saved: false, claimed: false, error: 'Session file not found in working directory or its parents' };
+  let outcome = { allowed: true, claimed: false };
+  const result = mutateSession(sessionProjectDir, (session) => {
+    const pending = session.pending_interaction;
+    if (!pending) {
+      if (claim.interactionId || (typeof claim.response === 'string' && claim.response.trim())) {
+        outcome = {
+          allowed: false, claimed: false, code: 'PENDING_INTERACTION_NOT_FOUND',
+          error: 'The pending interaction no longer exists. Refusing a stale relay command.',
+        };
+      }
+      return session;
+    }
+    if (pending.status !== 'waiting_for_user') {
+      outcome = {
+        allowed: false, claimed: false, code: 'PENDING_INTERACTION_ALREADY_CLAIMED',
+        error: `Pending interaction ${pending.interaction_id || 'unknown'} is already being relayed.`,
+      };
+      return session;
+    }
+    const reasoningEscalation = claim.reasoningEscalation === true;
+    if ((pending.relay_cycles || 1) <= 3 && reasoningEscalation) {
+      outcome = {
+        allowed: false, claimed: false, code: 'PENDING_INTERACTION_ESCALATION_NOT_REQUIRED',
+        error: 'Reasoning escalation is only allowed after three unresolved relay cycles.',
+      };
+      return session;
+    }
+    if ((pending.relay_cycles || 1) > 3 && !reasoningEscalation) {
+      outcome = {
+        allowed: false, claimed: false, code: 'PENDING_INTERACTION_RELAY_LIMIT',
+        error: `Pending interaction reached the maximum of 3 relay cycles and requires reasoning escalation.`,
+      };
+      return session;
+    }
+    const response = typeof claim.response === 'string' ? claim.response.trim() : '';
+    if (!response) {
+      outcome = {
+        allowed: false, claimed: false, code: 'PENDING_INTERACTION_REQUIRES_RESPONSE',
+        error: `Agent ${pending.agent} is waiting for the user's response.`,
+      };
+      return session;
+    }
+    const binding = reasoningEscalation ? {
+      provider: claim.provider || null,
+      provider_id: claim.providerId || null,
+      model: claim.model || null,
+      reasoning_configuration: claim.reasoningConfiguration || null,
+      catalog_snapshot_ref: claim.catalogSnapshotRef || null,
+    } : (pending.execution_binding || {});
+    const mismatches = [
+      ['interaction_id', pending.interaction_id, claim.interactionId],
+      ['agent', pending.agent, claim.agent],
+      ['task_id', pending.task_id, claim.taskId],
+      ['provider', binding.provider || null, claim.provider || null],
+      ['provider_id', binding.provider_id || null, claim.providerId || null],
+      ['model', binding.model || null, claim.model || null],
+      ['reasoning_configuration', binding.reasoning_configuration || null, claim.reasoningConfiguration || null],
+      ['catalog_snapshot_ref', binding.catalog_snapshot_ref || null, claim.catalogSnapshotRef || null],
+    ].filter(([, expected, actual]) => expected !== actual);
+    if (mismatches.length > 0) {
+      outcome = {
+        allowed: false, claimed: false, code: 'PENDING_INTERACTION_BINDING_MISMATCH',
+        error: `Pending interaction binding mismatch: ${mismatches.map(([field]) => field).join(', ')}.`,
+      };
+      return session;
+    }
+    const claimId = randomUUID();
+    session.pending_interaction = {
+      ...pending,
+      status: 'relay_in_flight',
+      ...(reasoningEscalation ? { escalation_execution_binding: binding } : {}),
+      relay_claim_id: claimId,
+      relay_started_at: claim.timestamp || new Date().toISOString(),
+      relay_lease_expires_at: claim.leaseExpiresAt || null,
+    };
+    outcome = { allowed: true, claimed: true, claimId };
+    return session;
+  });
+  return { ...result, ...outcome };
+}
+
+/** Restore a claimed relay after a controlled provider or contract failure. */
+export function releasePendingInteraction(projectDir, match = {}) {
+  const sessionProjectDir = findSessionProjectDir(projectDir);
+  if (!sessionProjectDir) return { saved: false, released: false, error: 'Session file not found in working directory or its parents' };
+  let released = false;
+  let settled = false;
+  const result = mutateSession(sessionProjectDir, (session) => {
+    const pending = session.pending_interaction;
+    if (!pending) {
+      settled = true;
+      return session;
+    }
+    if (pending.status === 'waiting_for_user' && (!match.interactionId || pending.interaction_id === match.interactionId)) {
+      released = true;
+      settled = true;
+      return session;
+    }
+    if (pending.status !== 'relay_in_flight') return session;
+    if (match.claimId && pending.relay_claim_id !== match.claimId) return session;
+    if (match.interactionId && pending.interaction_id !== match.interactionId) return session;
+    session.pending_interaction = { ...pending, status: 'waiting_for_user' };
+    delete session.pending_interaction.relay_claim_id;
+    delete session.pending_interaction.relay_started_at;
+    delete session.pending_interaction.relay_lease_expires_at;
+    released = true;
+    settled = true;
+    return session;
+  });
+  return { ...result, released, settled };
+}
+
 /** Clear a pending interaction only when the caller owns that relay. */
 export function clearPendingInteraction(projectDir, match = {}) {
   const sessionProjectDir = findSessionProjectDir(projectDir);
@@ -565,6 +1671,8 @@ export function clearPendingInteraction(projectDir, match = {}) {
     if (!pending) return session;
     if (match.agent && pending.agent !== match.agent) return session;
     if (match.taskId && pending.task_id !== match.taskId) return session;
+    if (match.interactionId && pending.interaction_id !== match.interactionId) return session;
+    if (match.claimId && pending.relay_claim_id !== match.claimId) return session;
     session.pending_interaction = null;
     if (session.agents?.[pending.agent]?.status === 'waiting_for_user') {
       session.agents[pending.agent].status = 'in_progress';
@@ -623,6 +1731,12 @@ export function recordAgentCompletion(projectDir, completion) {
   session.agents[agent].status = status;
   session.agents[agent].score = score || 0;
   session.agents[agent].completed_at = new Date().toISOString();
+  delete session.agents[agent].execution_claim_id;
+  delete session.agents[agent].execution_claim_state;
+  delete session.agents[agent].execution_claim_started_at;
+  delete session.agents[agent].execution_claim_expires_at;
+  delete session.agents[agent].execution_started_at;
+  delete session.agents[agent].execution_finished_at;
 
   // Add to completed agents list
   session.completed_agents = session.completed_agents || [];