codex-workflow-v2 2.0.0-beta.13.8 → 2.0.0-beta.14

package/src/state/lock.ts

@@ -0,0 +1,902 @@
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  unlinkSync,
+  writeFileSync,
+  type Stats,
+} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  STATE_SCHEMA_VERSION,
+  type PublicCoreTaskOperation,
+  type PublicWriterLease,
+  type WriterLease,
+} from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import { ensureDirectory, writeJsonAtomic } from '../fs-utils.js';
+
+const DEFAULT_LEASE_MS = 30 * 60 * 1000;
+const LOCK_ENTITY_PATTERN = /^(TASK|MS)-[0-9A-HJKMNP-TV-Z]{26}$/;
+const LOCK_FILE_PATTERN = /^(TASK|MS)-[0-9A-HJKMNP-TV-Z]{26}\.json$/;
+
+interface LeaseFileSnapshot {
+  lease: WriterLease;
+  identity: Pick<Stats, 'dev' | 'ino'>;
+  content: string;
+}
+
+export interface CoreTaskOperationMutex {
+  schemaVersion: typeof STATE_SCHEMA_VERSION;
+  kind: 'core-task-operation-mutex';
+  entityId: string;
+  operationId: string;
+  transitionId: string;
+  mutexId: string;
+  nonceSha256: string;
+  owner: 'workflow-core';
+  acquiredAt: string;
+  expiresAt: string;
+}
+
+export interface CoreTaskOperationHandle {
+  readonly __coreTaskOperationHandle?: never;
+}
+
+export interface WriterLeaseHandle {
+  readonly __writerLeaseHandle?: never;
+}
+
+interface CoreHandleRecord {
+  locksRoot: string;
+  trustedRoot?: string;
+  mutex: CoreTaskOperationMutex;
+  identity: Pick<Stats, 'dev' | 'ino'>;
+  descriptor: number;
+}
+
+interface LockFileSnapshot {
+  record: WriterLease | CoreTaskOperationMutex;
+  identity: Pick<Stats, 'dev' | 'ino'>;
+  content: string;
+}
+
+const coreHandles = new WeakMap<object, CoreHandleRecord>();
+const writerHandles = new WeakMap<object, {
+  locksRoot: string;
+  trustedRoot?: string;
+  snapshot: LeaseFileSnapshot;
+}>();
+
+export class WriterLockManager {
+  constructor(
+    private readonly locksRoot: string,
+    private readonly now: () => Date = () => new Date(),
+    private readonly trustedRoot?: string,
+  ) {
+    assertLockRootPath(locksRoot, trustedRoot);
+    ensureDirectory(locksRoot);
+    assertLockRootPath(locksRoot, trustedRoot);
+  }
+
+  acquire(entityId: string, owner: string, leaseMs = DEFAULT_LEASE_MS): WriterLease {
+    const file = this.file(entityId);
+    assertLockRootPath(this.locksRoot, this.trustedRoot);
+    const timestamp = this.now();
+    const lease: WriterLease = {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      entityId,
+      token: randomUUID(),
+      owner,
+      pid: process.pid,
+      hostname: os.hostname(),
+      acquiredAt: timestamp.toISOString(),
+      heartbeatAt: timestamp.toISOString(),
+      expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
+    };
+    let descriptor: number | null = null;
+    try {
+      descriptor = openSync(
+        file,
+        constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+        0o600,
+      );
+      writeFileSync(descriptor, `${JSON.stringify(lease, null, 2)}\n`, 'utf8');
+      closeSync(descriptor);
+      descriptor = null;
+      return lease;
+    } catch (error) {
+      if (descriptor !== null) closeSync(descriptor);
+      if (lstatIfPresent(file)) {
+        const snapshot = readLockSnapshot(this.locksRoot, entityId, this.trustedRoot);
+        if (isCoreTaskOperationMutex(snapshot.record)) {
+          throw new WorkflowError('LOCKED', `${entityId} already has a Core Task operation`, {
+            owner: snapshot.record.owner,
+            operationId: snapshot.record.operationId,
+            transitionId: snapshot.record.transitionId,
+            expiresAt: snapshot.record.expiresAt,
+            stale: lockExpiry(snapshot.record, file) <= timestamp.getTime(),
+          });
+        }
+        const current = snapshot.record;
+        throw new WorkflowError('LOCKED', `${entityId} already has a writer`, {
+          owner: current.owner,
+          pid: current.pid,
+          hostname: current.hostname,
+          heartbeatAt: current.heartbeatAt,
+          expiresAt: current.expiresAt,
+          stale: leaseExpiry(current, file) <= timestamp.getTime(),
+        });
+      }
+      throw error;
+    }
+  }
+
+  heartbeat(entityId: string, token: string, leaseMs = DEFAULT_LEASE_MS): WriterLease {
+    const timestamp = this.now();
+    const current = this.requireConsumableToken(entityId, token, timestamp);
+    const updated: WriterLease = {
+      ...current.lease,
+      heartbeatAt: timestamp.toISOString(),
+      expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
+    };
+    assertSameLeaseIdentity(this.file(entityId), current.identity);
+    writeJsonAtomic(this.file(entityId), updated);
+    return updated;
+  }
+
+  replaceCredential(entityId: string, owner: string, leaseMs = DEFAULT_LEASE_MS): WriterLease {
+    const timestamp = this.now();
+    const current = readLeaseSnapshotOrNull(this.locksRoot, entityId, this.trustedRoot);
+    if (!current) throw new WorkflowError('NOT_FOUND', `No writer lock for ${entityId}`);
+    if (current.lease.owner !== owner) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Only writer ${current.lease.owner} may replace the credential for ${entityId}.`, {
+        entityId,
+        owner: current.lease.owner,
+        actor: owner,
+      });
+    }
+    if (leaseExpiry(current.lease, this.file(entityId)) <= timestamp.getTime()) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Writer lock has expired for ${entityId}; explicit stale-lock repair is required.`, {
+        entityId,
+        expiresAt: current.lease.expiresAt,
+        requiredAction: 'locks repair',
+      });
+    }
+    const replacement: WriterLease = {
+      ...current.lease,
+      token: randomUUID(),
+      heartbeatAt: timestamp.toISOString(),
+      expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
+    };
+    assertSameLeaseIdentity(this.file(entityId), current.identity);
+    writeJsonAtomic(this.file(entityId), replacement);
+    return replacement;
+  }
+
+  replaceOrRecoverCredential(entityId: string, owner: string, leaseMs = DEFAULT_LEASE_MS): WriterLease {
+    const timestamp = this.now();
+    const current = readLeaseSnapshotOrNull(this.locksRoot, entityId, this.trustedRoot);
+    if (!current) return this.acquire(entityId, owner, leaseMs);
+    if (current.lease.owner !== owner) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Only writer ${current.lease.owner} may recover the credential for ${entityId}.`, {
+        entityId,
+        owner: current.lease.owner,
+        actor: owner,
+      });
+    }
+    const replacement: WriterLease = {
+      ...current.lease,
+      token: randomUUID(),
+      heartbeatAt: timestamp.toISOString(),
+      expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
+    };
+    // Recovery is exact-entity and exact-owner. Atomic replacement preserves the
+    // lock-file identity check and avoids a repository-wide delete/reacquire gap.
+    assertSameLeaseIdentity(this.file(entityId), current.identity);
+    writeJsonAtomic(this.file(entityId), replacement);
+    return replacement;
+  }
+
+
+  release(entityId: string, token: string): void {
+    const current = this.requireConsumableToken(entityId, token, this.now());
+    const file = this.file(entityId);
+    assertSameLeaseIdentity(file, current.identity);
+    unlinkSync(file);
+  }
+
+  prove(entityId: string, token: string): WriterLeaseHandle {
+    const snapshot = this.requireConsumableToken(entityId, token, this.now());
+    const handle = Object.freeze(Object.create(null)) as WriterLeaseHandle;
+    writerHandles.set(handle as object, {
+      locksRoot: path.resolve(this.locksRoot),
+      ...(this.trustedRoot === undefined ? {} : { trustedRoot: path.resolve(this.trustedRoot) }),
+      snapshot,
+    });
+    return handle;
+  }
+
+  proofBinding(handle: WriterLeaseHandle): {
+    entityId: string;
+    owner: string;
+    expiresAt: string;
+    tokenSha256: string;
+    contentSha256: string;
+  } {
+    const snapshot = assertWriterLeaseHandle(this.locksRoot, this.trustedRoot, handle, this.now());
+    return Object.freeze({
+      entityId: snapshot.lease.entityId,
+      owner: snapshot.lease.owner,
+      expiresAt: snapshot.lease.expiresAt,
+      tokenSha256: createHash('sha256').update(snapshot.lease.token).digest('hex'),
+      contentSha256: createHash('sha256').update(snapshot.content).digest('hex'),
+    });
+  }
+
+  inspect(entityId: string): WriterLease | null {
+    return inspectWriterLease(this.locksRoot, entityId, this.trustedRoot);
+  }
+
+  list(): WriterLease[] {
+    return listWriterLeases(this.locksRoot, this.trustedRoot);
+  }
+
+  repairStale(entityId: string): WriterLease {
+    const file = this.file(entityId);
+    const current = readLeaseSnapshotOrNull(this.locksRoot, entityId, this.trustedRoot);
+    if (!current) throw new WorkflowError('NOT_FOUND', `No writer lock for ${entityId}`);
+    const expiresAt = leaseExpiry(current.lease, file);
+    if (expiresAt > this.now().getTime()) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Writer lock is not stale for ${entityId}`, {
+        expiresAt: current.lease.expiresAt,
+      });
+    }
+    assertSameLeaseIdentity(file, current.identity);
+    unlinkSync(file);
+    return current.lease;
+  }
+
+  private requireConsumableToken(entityId: string, token: string, now: Date): LeaseFileSnapshot {
+    const current = readLeaseSnapshotOrNull(this.locksRoot, entityId, this.trustedRoot);
+    if (!current) throw new WorkflowError('NOT_FOUND', `No writer lock for ${entityId}`);
+    if (current.lease.token !== token) {
+      throw new WorkflowError('LOCK_TOKEN_INVALID', `Writer token does not own ${entityId}`);
+    }
+    if (leaseExpiry(current.lease, this.file(entityId)) <= now.getTime()) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Writer lock has expired for ${entityId}; explicit stale-lock repair is required.`, {
+        entityId,
+        expiresAt: current.lease.expiresAt,
+        requiredAction: 'locks repair',
+      });
+    }
+    return current;
+  }
+
+  private file(entityId: string): string {
+    assertLockEntity(entityId);
+    return path.join(this.locksRoot, `${entityId}.json`);
+  }
+}
+
+export function listWriterLeases(locksRoot: string, trustedRoot?: string): WriterLease[] {
+  if (!lstatIfPresent(locksRoot)) return [];
+  assertLockRootPath(locksRoot, trustedRoot);
+  return readdirSync(locksRoot, { withFileTypes: true })
+    .filter((entry) => LOCK_FILE_PATTERN.test(entry.name))
+    .flatMap((entry) => {
+      const snapshot = readLockSnapshot(
+      locksRoot,
+      entry.name.slice(0, -'.json'.length),
+      trustedRoot,
+      );
+      return isCoreTaskOperationMutex(snapshot.record) ? [] : [snapshot.record];
+    })
+    .sort((left, right) => left.entityId.localeCompare(right.entityId));
+}
+
+export function inspectWriterLease(
+  locksRoot: string,
+  entityId: string,
+  trustedRoot?: string,
+): WriterLease | null {
+  assertLockEntity(entityId);
+  if (!lstatIfPresent(locksRoot)) return null;
+  const file = path.join(locksRoot, `${entityId}.json`);
+  if (!lstatIfPresent(file)) return null;
+  const record = readLockSnapshot(locksRoot, entityId, trustedRoot).record;
+  return isCoreTaskOperationMutex(record) ? null : record;
+}
+
+export function listCoreTaskOperationMutexes(
+  locksRoot: string,
+  trustedRoot?: string,
+): CoreTaskOperationMutex[] {
+  if (!lstatIfPresent(locksRoot)) return [];
+  assertLockRootPath(locksRoot, trustedRoot);
+  return readdirSync(locksRoot, { withFileTypes: true })
+    .filter((entry) => LOCK_FILE_PATTERN.test(entry.name))
+    .flatMap((entry) => {
+      const record = readLockSnapshot(
+        locksRoot,
+        entry.name.slice(0, -'.json'.length),
+        trustedRoot,
+      ).record;
+      return isCoreTaskOperationMutex(record) ? [record] : [];
+    })
+    .sort((left, right) => left.entityId.localeCompare(right.entityId));
+}
+
+export function toPublicWriterLease(lease: WriterLease, now: Date): PublicWriterLease {
+  const expiresAt = leaseExpiry(lease, '<writer-lease>');
+  return {
+    schemaVersion: lease.schemaVersion,
+    entityId: lease.entityId,
+    owner: lease.owner,
+    pid: lease.pid,
+    hostname: lease.hostname,
+    acquiredAt: lease.acquiredAt,
+    heartbeatAt: lease.heartbeatAt,
+    expiresAt: lease.expiresAt,
+    stale: expiresAt <= now.getTime(),
+  };
+}
+
+function readLeaseSnapshotOrNull(
+  locksRoot: string,
+  entityId: string,
+  trustedRoot?: string,
+): LeaseFileSnapshot | null {
+  assertLockEntity(entityId);
+  if (!lstatIfPresent(locksRoot)) return null;
+  assertLockRootPath(locksRoot, trustedRoot);
+  const file = path.join(locksRoot, `${entityId}.json`);
+  if (!lstatIfPresent(file)) return null;
+  return readLeaseSnapshot(locksRoot, entityId, trustedRoot);
+}
+
+function readLeaseSnapshot(
+  locksRoot: string,
+  entityId: string,
+  trustedRoot?: string,
+): LeaseFileSnapshot {
+  const snapshot = readLockSnapshot(locksRoot, entityId, trustedRoot);
+  if (isCoreTaskOperationMutex(snapshot.record)) {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', `Writer token does not own ${entityId}`);
+  }
+  return { lease: snapshot.record, identity: snapshot.identity, content: snapshot.content };
+}
+
+function readLockSnapshot(
+  locksRoot: string,
+  entityId: string,
+  trustedRoot?: string,
+): LockFileSnapshot {
+  assertLockEntity(entityId);
+  assertLockRootPath(locksRoot, trustedRoot);
+  const file = path.join(locksRoot, `${entityId}.json`);
+  const boundary = trustedBoundary(locksRoot, trustedRoot);
+  assertNoSymlinkBelowBoundary(file, boundary, 'Writer lease path');
+  const before = lstatIfPresent(file);
+  if (!before) throw new WorkflowError('NOT_FOUND', `No writer lock for ${entityId}`);
+  if (before.isSymbolicLink() || !before.isFile()) {
+    throw new WorkflowError('STATE_CORRUPT', `Writer lease must be a regular file: ${file}`);
+  }
+  let descriptor: number | null = null;
+  try {
+    descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const opened = fstatSync(descriptor);
+    if (!sameIdentity(before, opened) || !opened.isFile()) {
+      throw new WorkflowError('STATE_CONFLICT', `Writer lease changed while opening: ${file}`);
+    }
+    const content = readFileSync(descriptor, 'utf8');
+    let record: WriterLease | CoreTaskOperationMutex;
+    try {
+      record = JSON.parse(content) as WriterLease | CoreTaskOperationMutex;
+    } catch (error) {
+      throw new WorkflowError('STATE_CORRUPT', `Cannot read JSON state: ${file}`, {
+        cause: error instanceof Error ? error.message : String(error),
+      });
+    }
+    validateLockRecord(record, entityId, file);
+    const after = lstatIfPresent(file);
+    if (!after || !sameIdentity(opened, after)) {
+      throw new WorkflowError('STATE_CONFLICT', `Writer lease changed while reading: ${file}`);
+    }
+    return { record, identity: { dev: opened.dev, ino: opened.ino }, content };
+  } finally {
+    if (descriptor !== null) closeSync(descriptor);
+  }
+}
+
+export class CoreTaskOperationLockManager {
+  constructor(
+    private readonly locksRoot: string,
+    private readonly now: () => Date = () => new Date(),
+    private readonly trustedRoot?: string,
+  ) {
+    assertLockRootPath(locksRoot, trustedRoot);
+    ensureDirectory(locksRoot);
+    assertLockRootPath(locksRoot, trustedRoot);
+  }
+
+  acquire(input: {
+    entityId: string;
+    operationId: string;
+    transitionId: string;
+    leaseMs?: number;
+  }): CoreTaskOperationHandle {
+    assertLockEntity(input.entityId);
+    if (!input.entityId.startsWith('TASK-')) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Core corrective-replan operations require a Task entity.');
+    }
+    if (!/^[a-f0-9]{64}$/.test(input.operationId)) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Core Task operation id must be lowercase SHA-256.');
+    }
+    if (!isSupportedCoreTaskTransition(input.transitionId)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `Unsupported Core Task transition: ${input.transitionId}`);
+    }
+    const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS;
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || leaseMs > DEFAULT_LEASE_MS) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Core Task operation lease must be between 1 ms and 30 minutes.');
+    }
+    const timestamp = this.now();
+    const nonce = randomUUID();
+    const mutex: CoreTaskOperationMutex = {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      kind: 'core-task-operation-mutex',
+      entityId: input.entityId,
+      operationId: input.operationId,
+      transitionId: input.transitionId,
+      mutexId: randomUUID(),
+      nonceSha256: createHash('sha256').update(nonce).digest('hex'),
+      owner: 'workflow-core',
+      acquiredAt: timestamp.toISOString(),
+      expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
+    };
+    const file = path.join(this.locksRoot, `${input.entityId}.json`);
+    let descriptor: number | null = null;
+    try {
+      descriptor = openSync(file, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+      writeFileSync(descriptor, `${JSON.stringify(mutex, null, 2)}\n`, 'utf8');
+      closeSync(descriptor);
+      descriptor = null;
+    } catch (error) {
+      if (descriptor !== null) closeSync(descriptor);
+      if (lstatIfPresent(file)) {
+        const current = readLockSnapshot(this.locksRoot, input.entityId, this.trustedRoot).record;
+        throw new WorkflowError('LOCKED', `${input.entityId} already has a Task operation owner`, {
+          owner: isCoreTaskOperationMutex(current) ? current.owner : current.owner,
+          ...(isCoreTaskOperationMutex(current) ? {
+            operationId: current.operationId,
+            transitionId: current.transitionId,
+          } : {}),
+          expiresAt: current.expiresAt,
+          stale: lockExpiry(current, file) <= timestamp.getTime(),
+        });
+      }
+      throw error;
+    }
+    return issueCoreHandle(this.locksRoot, this.trustedRoot, mutex);
+  }
+
+  repairExpiredOrphan(entityId: string, assertNoJournal: (mutex: Readonly<CoreTaskOperationMutex>) => void): PublicCoreTaskOperation & { kind: 'core-task-operation'; repaired: true } {
+    assertLockEntity(entityId);
+    const file = path.join(this.locksRoot, `${entityId}.json`);
+    const snapshot = readLockSnapshot(this.locksRoot, entityId, this.trustedRoot);
+    if (!isCoreTaskOperationMutex(snapshot.record)) {
+      throw new WorkflowError('LOCKED', 'Orphan Core repair requires an exact Core mutex.');
+    }
+    if (lockExpiry(snapshot.record, file) > this.now().getTime()) {
+      throw new WorkflowError('LOCKED', 'An active Core operation cannot be repaired.');
+    }
+    assertNoJournal(snapshot.record);
+    assertSameLeaseIdentity(file, snapshot.identity);
+    const current = readLockSnapshot(this.locksRoot, entityId, this.trustedRoot);
+    if (!isCoreTaskOperationMutex(current.record) || current.record.mutexId !== snapshot.record.mutexId
+      || current.content !== snapshot.content) {
+      throw new WorkflowError('STATE_CONFLICT', 'Core mutex changed during orphan repair.');
+    }
+    assertSameLeaseIdentity(file, current.identity);
+    unlinkSync(file);
+    return { ...toPublicCoreTaskOperation(snapshot.record, this.now()), kind: 'core-task-operation', repaired: true };
+  }
+
+  acquireForRecovery(input: {
+    entityId: string;
+    operationId: string;
+    transitionId: string;
+    leaseMs?: number;
+  }): CoreTaskOperationHandle {
+    assertLockEntity(input.entityId);
+    if (!input.entityId.startsWith('TASK-')
+      || !/^[a-f0-9]{64}$/.test(input.operationId)
+      || !isSupportedCoreTaskTransition(input.transitionId)) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Invalid Core Task recovery operation identity.');
+    }
+    const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS;
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || leaseMs > DEFAULT_LEASE_MS) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Core Task recovery lease must be between 1 ms and 30 minutes.');
+    }
+    const file = path.join(this.locksRoot, `${input.entityId}.json`);
+    if (!lstatIfPresent(file)) return this.acquire(input);
+    const now = this.now();
+    const snapshot = readLockSnapshot(this.locksRoot, input.entityId, this.trustedRoot);
+    if (!isCoreTaskOperationMutex(snapshot.record)
+      || snapshot.record.operationId !== input.operationId
+      || snapshot.record.transitionId !== input.transitionId) {
+      throw new WorkflowError('LOCKED', `${input.entityId} is owned by another Task operation.`, {
+        expiresAt: snapshot.record.expiresAt,
+      });
+    }
+    if (lockExpiry(snapshot.record, file) > now.getTime()) {
+      throw new WorkflowError('LOCKED', `${input.entityId} still has an active Core Task operation.`, {
+        operationId: snapshot.record.operationId,
+        expiresAt: snapshot.record.expiresAt,
+      });
+    }
+    assertSameLeaseIdentity(file, snapshot.identity);
+    unlinkSync(file);
+    return this.acquire(input);
+  }
+
+  transferFromWriter(
+    writerHandle: WriterLeaseHandle,
+    input: { entityId: string; operationId: string; transitionId: 'task.coordination.corrective-yield'; leaseMs?: number },
+  ): CoreTaskOperationHandle {
+    const writer = assertWriterLeaseHandle(this.locksRoot, this.trustedRoot, writerHandle, this.now());
+    if (writer.lease.entityId !== input.entityId) {
+      throw new WorkflowError('LOCK_TOKEN_INVALID', `Writer lease does not own ${input.entityId}`);
+    }
+    const mutex = this.materializeMutex(input);
+    const file = path.join(this.locksRoot, `${input.entityId}.json`);
+    assertSameLeaseIdentity(file, writer.identity);
+    writeJsonAtomic(file, mutex);
+    writerHandles.delete(writerHandle as object);
+    return issueCoreHandle(this.locksRoot, this.trustedRoot, mutex);
+  }
+
+  acquireYieldRecovery(input: {
+    entityId: string;
+    operationId: string;
+    transitionId: 'task.coordination.corrective-yield';
+    expectedWriterContentSha256: string;
+    expectedWriterTokenSha256: string;
+    leaseMs?: number;
+  }): CoreTaskOperationHandle {
+    assertHash64(input.expectedWriterContentSha256, 'Expected writer lease content hash');
+    assertHash64(input.expectedWriterTokenSha256, 'Expected writer lease token hash');
+    const file = path.join(this.locksRoot, `${input.entityId}.json`);
+    if (!lstatIfPresent(file)) return this.acquire(input);
+    const snapshot = readLockSnapshot(this.locksRoot, input.entityId, this.trustedRoot);
+    if (isCoreTaskOperationMutex(snapshot.record)) return this.acquireForRecovery(input);
+    const now = this.now();
+    if (leaseExpiry(snapshot.record, file) > now.getTime()) {
+      throw new WorkflowError('LOCKED', `${input.entityId} still has an active writer lease.`);
+    }
+    if (createHash('sha256').update(snapshot.content).digest('hex') !== input.expectedWriterContentSha256
+      || createHash('sha256').update(snapshot.record.token).digest('hex') !== input.expectedWriterTokenSha256) {
+      throw new WorkflowError('STATE_CONFLICT', 'Stale writer lease does not match the corrective-yield intent.');
+    }
+    const mutex = this.materializeMutex(input);
+    assertSameLeaseIdentity(file, snapshot.identity);
+    writeJsonAtomic(file, mutex);
+    return issueCoreHandle(this.locksRoot, this.trustedRoot, mutex);
+  }
+
+  release(handle: CoreTaskOperationHandle): void {
+    const record = assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now());
+    const file = path.join(this.locksRoot, `${record.entityId}.json`);
+    const snapshot = readLockSnapshot(this.locksRoot, record.entityId, this.trustedRoot);
+    if (!isCoreTaskOperationMutex(snapshot.record) || snapshot.record.mutexId !== record.mutexId) {
+      throw new WorkflowError('LOCK_TOKEN_INVALID', `Core Task operation does not own ${record.entityId}`);
+    }
+    assertSameLeaseIdentity(file, snapshot.identity);
+    unlinkSync(file);
+    closeSync(coreHandles.get(handle as object)!.descriptor);
+    coreHandles.delete(handle as object);
+  }
+
+  private materializeMutex(input: {
+    entityId: string;
+    operationId: string;
+    transitionId: string;
+    leaseMs?: number;
+  }): CoreTaskOperationMutex {
+    assertLockEntity(input.entityId);
+    if (!input.entityId.startsWith('TASK-') || !/^[a-f0-9]{64}$/.test(input.operationId)
+      || !isSupportedCoreTaskTransition(input.transitionId)) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Invalid Core Task operation identity.');
+    }
+    const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS;
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || leaseMs > DEFAULT_LEASE_MS) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Core Task operation lease must be between 1 ms and 30 minutes.');
+    }
+    const timestamp = this.now();
+    return {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      kind: 'core-task-operation-mutex',
+      entityId: input.entityId,
+      operationId: input.operationId,
+      transitionId: input.transitionId,
+      mutexId: randomUUID(),
+      nonceSha256: createHash('sha256').update(randomUUID()).digest('hex'),
+      owner: 'workflow-core',
+      acquiredAt: timestamp.toISOString(),
+      expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
+    };
+  }
+
+}
+
+export function assertCoreTaskOperationHandle(
+  locksRoot: string,
+  trustedRoot: string | undefined,
+  handle: unknown,
+  now: Date,
+  expected?: { entityId?: string; operationId?: string; transitionId?: string },
+): CoreTaskOperationMutex {
+  if (!handle || typeof handle !== 'object') {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', 'A genuine Core Task operation handle is required.');
+  }
+  const issued = coreHandles.get(handle);
+  if (!issued || issued.locksRoot !== path.resolve(locksRoot)
+    || (issued.trustedRoot ?? undefined) !== (trustedRoot === undefined ? undefined : path.resolve(trustedRoot))) {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', 'A genuine Core Task operation handle is required.');
+  }
+  if (expected?.entityId !== undefined && issued.mutex.entityId !== expected.entityId) {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', `Core Task operation does not own ${expected.entityId}`);
+  }
+  if (expected?.operationId !== undefined && issued.mutex.operationId !== expected.operationId) {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', 'Core Task operation id mismatch.');
+  }
+  if (expected?.transitionId !== undefined && issued.mutex.transitionId !== expected.transitionId) {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', 'Core Task operation transition mismatch.');
+  }
+  const snapshot = readLockSnapshot(locksRoot, issued.mutex.entityId, trustedRoot);
+  const anchored = fstatSync(issued.descriptor);
+  if (!isCoreTaskOperationMutex(snapshot.record)
+    || snapshot.record.mutexId !== issued.mutex.mutexId
+    || snapshot.record.nonceSha256 !== issued.mutex.nonceSha256
+    || !sameIdentity(snapshot.identity, issued.identity)
+    || !sameIdentity(snapshot.identity, anchored)) {
+    closeSync(issued.descriptor);
+    coreHandles.delete(handle);
+    throw new WorkflowError('LOCK_TOKEN_INVALID', `Core Task operation does not own ${issued.mutex.entityId}`);
+  }
+  if (lockExpiry(snapshot.record, path.join(locksRoot, `${issued.mutex.entityId}.json`)) <= now.getTime()) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Core Task operation has expired for ${issued.mutex.entityId}.`);
+  }
+  return snapshot.record;
+}
+
+export function inspectCoreTaskOperationMutex(
+  locksRoot: string,
+  entityId: string,
+  trustedRoot?: string,
+): CoreTaskOperationMutex | null {
+  assertLockEntity(entityId);
+  if (!lstatIfPresent(locksRoot)) return null;
+  const file = path.join(locksRoot, `${entityId}.json`);
+  if (!lstatIfPresent(file)) return null;
+  const record = readLockSnapshot(locksRoot, entityId, trustedRoot).record;
+  return isCoreTaskOperationMutex(record) ? record : null;
+}
+
+export function toPublicCoreTaskOperation(
+  mutex: CoreTaskOperationMutex,
+  now: Date,
+): PublicCoreTaskOperation {
+  return {
+    schemaVersion: mutex.schemaVersion,
+    entityId: mutex.entityId,
+    operationId: mutex.operationId,
+    transitionId: mutex.transitionId,
+    owner: mutex.owner,
+    acquiredAt: mutex.acquiredAt,
+    expiresAt: mutex.expiresAt,
+    stale: lockExpiry(mutex, '<core-task-operation>') <= now.getTime(),
+  };
+}
+
+function assertLockRootPath(locksRoot: string, trustedRoot: string | undefined): void {
+  const boundary = trustedBoundary(locksRoot, trustedRoot);
+  assertNoSymlinkBelowBoundary(locksRoot, boundary, 'Writer lock root');
+  const stat = lstatIfPresent(locksRoot);
+  if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) {
+    throw new WorkflowError('STATE_CORRUPT', `Writer lock root must be a directory: ${locksRoot}`);
+  }
+}
+
+function assertNoSymlinkBelowBoundary(candidate: string, boundary: string, label: string): void {
+  const resolvedCandidate = path.resolve(candidate);
+  if (resolvedCandidate !== boundary && !resolvedCandidate.startsWith(`${boundary}${path.sep}`)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} is outside of the trusted root: ${candidate}`, {
+      trustedRoot: boundary,
+    });
+  }
+  let current = boundary;
+  for (const segment of path.relative(boundary, resolvedCandidate).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    const stat = lstatIfPresent(current);
+    if (!stat) return;
+    if (stat.isSymbolicLink()) {
+      throw new WorkflowError('STATE_CORRUPT', `${label} must not traverse a symlink: ${candidate}`, {
+        symlinkPath: current,
+      });
+    }
+  }
+}
+
+function trustedBoundary(locksRoot: string, trustedRoot: string | undefined): string {
+  const boundary = path.resolve(trustedRoot ?? path.dirname(locksRoot));
+  const stat = lstatIfPresent(boundary);
+  if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new WorkflowError('STATE_CORRUPT', `Writer lock trusted root must be an existing directory: ${boundary}`);
+  }
+  return boundary;
+}
+
+function assertSameLeaseIdentity(file: string, expected: Pick<Stats, 'dev' | 'ino'>): void {
+  const current = lstatIfPresent(file);
+  if (!current || current.isSymbolicLink() || !current.isFile() || !sameIdentity(expected, current)) {
+    throw new WorkflowError('STATE_CONFLICT', `Writer lease changed before mutation: ${file}`);
+  }
+}
+
+function leaseExpiry(lease: WriterLease, file: string): number {
+  if (typeof lease.expiresAt !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', `Writer lease expiresAt must be a finite ISO timestamp: ${file}`);
+  }
+  const expiresAt = Date.parse(lease.expiresAt);
+  if (!Number.isFinite(expiresAt) || new Date(expiresAt).toISOString() !== lease.expiresAt) {
+    throw new WorkflowError('STATE_CORRUPT', `Writer lease expiresAt must be a finite ISO timestamp: ${file}`, {
+      expiresAt: lease.expiresAt,
+    });
+  }
+  return expiresAt;
+}
+
+function lockExpiry(record: WriterLease | CoreTaskOperationMutex, file: string): number {
+  return leaseExpiry(record as WriterLease, file);
+}
+
+function isCoreTaskOperationMutex(record: WriterLease | CoreTaskOperationMutex): record is CoreTaskOperationMutex {
+  return (record as { kind?: unknown }).kind === 'core-task-operation-mutex';
+}
+
+function validateLockRecord(
+  record: WriterLease | CoreTaskOperationMutex,
+  expectedEntityId: string,
+  file: string,
+): void {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    throw new WorkflowError('STATE_CORRUPT', `Task operation lock must be an object: ${file}`);
+  }
+  if (record.schemaVersion !== STATE_SCHEMA_VERSION || record.entityId !== expectedEntityId) {
+    throw new WorkflowError('STATE_CORRUPT', `Task operation lock identity mismatch: ${file}`);
+  }
+  if (isCoreTaskOperationMutex(record)) {
+    const keys = Object.keys(record).sort();
+    const expected = [
+      'acquiredAt', 'entityId', 'expiresAt', 'kind', 'mutexId', 'nonceSha256', 'operationId',
+      'owner', 'schemaVersion', 'transitionId',
+    ].sort();
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+      throw new WorkflowError('STATE_CORRUPT', `Core Task operation lock has unknown or missing fields: ${file}`);
+    }
+    if (record.owner !== 'workflow-core' || !isSupportedCoreTaskTransition(record.transitionId)) {
+      throw new WorkflowError('STATE_CORRUPT', `Core Task operation lock semantic identity mismatch: ${file}`);
+    }
+    assertHash64(record.operationId, 'Core Task operation id');
+    assertHash64(record.nonceSha256, 'Core Task operation nonce hash');
+    if (typeof record.mutexId !== 'string' || !/^[0-9a-f-]{36}$/.test(record.mutexId)) {
+      throw new WorkflowError('STATE_CORRUPT', `Core Task operation mutexId is invalid: ${file}`);
+    }
+    const acquiredAt = typeof record.acquiredAt === 'string' ? Date.parse(record.acquiredAt) : Number.NaN;
+    if (!Number.isFinite(acquiredAt) || new Date(acquiredAt).toISOString() !== record.acquiredAt) {
+      throw new WorkflowError('STATE_CORRUPT', `Core Task operation acquiredAt is invalid: ${file}`);
+    }
+  }
+  lockExpiry(record, file);
+}
+
+function assertWriterLeaseHandle(
+  locksRoot: string,
+  trustedRoot: string | undefined,
+  handle: unknown,
+  now: Date,
+): LeaseFileSnapshot {
+  if (!handle || typeof handle !== 'object') {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', 'A genuine writer lease handle is required.');
+  }
+  const issued = writerHandles.get(handle);
+  if (!issued || issued.locksRoot !== path.resolve(locksRoot)
+    || (issued.trustedRoot ?? undefined) !== (trustedRoot === undefined ? undefined : path.resolve(trustedRoot))) {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', 'A genuine writer lease handle is required.');
+  }
+  const current = readLeaseSnapshot(locksRoot, issued.snapshot.lease.entityId, trustedRoot);
+  if (!sameIdentity(current.identity, issued.snapshot.identity)
+    || current.lease.token !== issued.snapshot.lease.token
+    || current.content !== issued.snapshot.content) {
+    throw new WorkflowError('LOCK_TOKEN_INVALID', 'Writer lease changed after proof issuance.');
+  }
+  if (leaseExpiry(current.lease, path.join(locksRoot, `${current.lease.entityId}.json`)) <= now.getTime()) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Writer lease has expired for ${current.lease.entityId}.`);
+  }
+  return current;
+}
+
+function issueCoreHandle(
+  locksRoot: string,
+  trustedRoot: string | undefined,
+  mutex: CoreTaskOperationMutex,
+): CoreTaskOperationHandle {
+  const issued = readLockSnapshot(locksRoot, mutex.entityId, trustedRoot);
+  if (!isCoreTaskOperationMutex(issued.record) || issued.record.mutexId !== mutex.mutexId) {
+    throw new WorkflowError('STATE_CONFLICT', 'Core Task operation changed during lock transfer.');
+  }
+  const file = path.join(locksRoot, `${mutex.entityId}.json`);
+  let descriptor: number | null = null;
+  try {
+    descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const anchored = fstatSync(descriptor);
+    if (!anchored.isFile() || !sameIdentity(issued.identity, anchored)) {
+      throw new WorkflowError('STATE_CONFLICT', 'Core Task operation changed while anchoring its handle.');
+    }
+  } catch (error) {
+    if (descriptor !== null) closeSync(descriptor);
+    throw error;
+  }
+  const handle = Object.freeze(Object.create(null)) as CoreTaskOperationHandle;
+  coreHandles.set(handle as object, {
+    locksRoot: path.resolve(locksRoot),
+    ...(trustedRoot === undefined ? {} : { trustedRoot: path.resolve(trustedRoot) }),
+    mutex,
+    identity: issued.identity,
+    descriptor,
+  });
+  return handle;
+}
+
+function isSupportedCoreTaskTransition(value: string): boolean {
+  return value === 'task.plan.corrective-replan' || value === 'task.coordination.corrective-yield';
+}
+
+function assertHash64(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be a lowercase SHA-256 value.`);
+  }
+}
+
+function assertLockEntity(entityId: string): void {
+  if (!LOCK_ENTITY_PATTERN.test(entityId)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Invalid lock entity: ${entityId}`);
+  }
+}
+
+function sameIdentity(
+  left: Pick<Stats, 'dev' | 'ino'>,
+  right: Pick<Stats, 'dev' | 'ino'>,
+): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function lstatIfPresent(candidate: string): Stats | null {
+  try {
+    return lstatSync(candidate);
+  } catch (error) {
+    if (isNodeError(error) && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error;
+}