release-skill 0.4.1 → 0.5.0

package/src/artifacts/project-lock.mjs

@@ -1,23 +1,35 @@
 /**
- * Shared project lock for artifact commands.
+ * Shared project lock for artifact commands (G4: token-lock adoption).
  *
  * All mutating artifact commands (apply, accept, recover, resolve submit,
- * prepare) share a single project lock domain. The lock is acquired via
- * exclusive `mkdir(.release-skill/lock)` — atomic on all POSIX filesystems.
+ * prepare) share a single project lock domain. The lock is acquired via the
+ * Foundation in-flight `token-lock` mechanism: `.release-skill/lock` is a
+ * SINGLE FILE (0600) holding the lock record
+ * `{schemaVersion:1, owner:<owner6-JSON string>, tokenDigest, acquiredAt}`.
+ * The owner record is published atomically together with the lock — there is
+ * no ownerless-lock window (G4 conflict-surface.md 第六节).
  *
  * Owner record contains: pid, host, bootId (or session id), nonce, command,
- * startedAt. The owner JSON and parent directory are fsynced before the
- * acquire call returns success.
+ * startedAt. It is embedded as the lock record `owner` string.
  *
- * TTL is informational only — aging a lock directory never permits automatic
- * deletion. Only the exact owner can release, or an operator can break the
- * lock with `breakProjectLock` which requires matching the exact owner and
- * writes audit evidence.
+ * TTL is informational only — aging a lock never permits automatic deletion.
+ * Only the exact owner can release (token + identity), or an operator can
+ * break the lock with `breakProjectLock` which requires matching the exact
+ * owner and writes audit evidence before recovery.
+ *
+ * Old lock domain: `.release-skill/lock` as a DIRECTORY (with `.owner`).
+ * Detecting a directory at the lock path fails closed with
+ * LOCK_MIGRATION_REQUIRED — never auto-deleted, never auto-converted
+ * (same-path different-form makes old/new code mutually exclusive).
+ *
+ * Bridge: in-flight Foundation capabilities are imported through
+ * `../core/foundation-inflight.mjs` (relative-path import of the Foundation
+ * workspace; released form must be the bundle).
  *
  * @module artifacts/project-lock
  */
 
-import { mkdir, rm, writeFile, readFile, readdir, stat, lstat, open } from 'node:fs/promises';
+import { mkdir, writeFile, lstat, open } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { hostname } from 'node:os';
@@ -27,15 +39,25 @@ import {
   ReleaseError,
   TRANSACTION_INCOMPLETE,
   PATH_UNSAFE,
+  LOCK_MIGRATION_REQUIRED,
 } from '../core/errors.mjs';
+import {
+  acquireFilesystemLock,
+  inspectFilesystemLock,
+  releaseFilesystemLock,
+  recoverFilesystemLock,
+  HARNESS_ERROR_KINDS as INFLIGHT_KINDS,
+} from '../core/foundation-inflight.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const LOCK_DIR_NAME = 'lock';
-const OWNER_FILE_NAME = '.owner';
+/** Foundation token-lock relative path (single file — replaces old directory). */
+const LOCK_REL_PATH = join('.release-skill', 'lock');
 const AUDIT_DIR_NAME = 'lock-audit';
+/** Foundation assertOwner upper bound on the owner string (token-lock.mjs). */
+const MAX_OWNER_JSON_LENGTH = 200;
 
 /** All owner fields that must match exactly. */
 const OWNER_FIELDS = ['pid', 'host', 'bootId', 'nonce', 'command', 'startedAt'];
@@ -87,12 +109,8 @@ function getBootId() {
 // Internal: path helpers
 // ---------------------------------------------------------------------------
 
-function lockDir(root) {
-  return join(root, '.release-skill', LOCK_DIR_NAME);
-}
-
-function ownerPath(root) {
-  return join(lockDir(root), OWNER_FILE_NAME);
+function lockPath(root) {
+  return join(root, LOCK_REL_PATH);
 }
 
 function auditDir(root) {
@@ -214,6 +232,10 @@ function sanitizeReason(reason) {
     .replace(/(^|[\s("'=])(?:[A-Za-z]:[\\/]|\\\\)[^\s,;:'")\]]+/g, '$1<absolute-path>');
 }
 
+// ---------------------------------------------------------------------------
+// Internal: durability observation (real fsync at wrapper boundaries)
+// ---------------------------------------------------------------------------
+
 async function emitDurability(observer, event) {
   if (!observer) return;
   try {
@@ -233,124 +255,140 @@ async function fsyncDirObserved(dirPath, observer) {
   await emitDurability(observer, { operation: 'fsync-dir', path: dirPath });
 }
 
-// ---------------------------------------------------------------------------
-// Internal: assert owner matches on disk
-// ---------------------------------------------------------------------------
-
 /**
- * Read the persisted owner from disk and compare with the expected owner.
- * All six fields (pid, host, bootId, nonce, command, startedAt) must match
- * exactly.
+ * Fsync a file by path — opens, syncs, closes.
  *
- * @param {object} expected - The expected owner record.
- * @param {string} root - Repository root.
- * @returns {Promise<void>}
- * @throws {ReleaseError} TRANSACTION_INCOMPLETE if owner mismatch or missing.
+ * @param {string} filePath
  */
-async function assertOwnerOnDisk(expected, root) {
-  let raw;
+async function fsyncFile(filePath) {
+  const fh = await open(filePath, 'r');
   try {
-    raw = await readFile(ownerPath(root), 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      throw new ReleaseError(
-        TRANSACTION_INCOMPLETE,
-        'project lock directory does not exist — ownership lost',
-        { root },
-      );
-    }
-    throw err;
+    await fh.sync();
+  } finally {
+    await fh.close();
   }
+}
 
-  let actual;
+/**
+ * Fsync a directory by path.
+ *
+ * @param {string} dirPath
+ */
+async function fsyncDir(dirPath) {
+  const fh = await open(dirPath, 'r');
   try {
-    actual = JSON.parse(raw);
-  } catch {
-    throw new ReleaseError(
-      TRANSACTION_INCOMPLETE,
-      'project lock owner file is corrupt',
-      { root },
-    );
+    await fh.sync();
+  } finally {
+    await fh.close();
   }
+}
 
-  for (const field of OWNER_FIELDS) {
-    if (actual[field] !== expected[field]) {
-      throw new ReleaseError(
-        TRANSACTION_INCOMPLETE,
-        `project lock owner does not match — field "${field}" differs`,
-        { root, field, expected: field === 'nonce' ? expected[field]?.slice(0, 8) : undefined },
-      );
-    }
+// ---------------------------------------------------------------------------
+// Internal: Foundation error mapping (G4 conflict-surface.md 第五节)
+// ---------------------------------------------------------------------------
+
+function mapKindToCode(kind) {
+  switch (kind) {
+    case INFLIGHT_KINDS.STORE_LOCKED:
+    case INFLIGHT_KINDS.LOCK_CORRUPT:
+    case INFLIGHT_KINDS.LOCK_RECOVERY_REFUSED:
+    case INFLIGHT_KINDS.EXCLUSIVE_PUBLISH_CONFLICT:
+      return TRANSACTION_INCOMPLETE;
+    case INFLIGHT_KINDS.UNSAFE_STATE_ENTRY:
+      return PATH_UNSAFE;
+    default:
+      // 未知 kind → fail-closed，默认拒绝
+      return PATH_UNSAFE;
   }
 }
 
 /**
- * Remove the lock directory only if the persisted owner matches exactly.
- * After removal, fsync the parent .release-skill directory for durability.
+ * Map a Foundation mechanism error to a local ReleaseError.
  *
- * @param {object} expected - The expected owner record.
- * @param {string} root - Repository root.
- * @param {(event: object) => Promise<void>} [durabilityObserver] - Observe completed durability operations.
- * @returns {Promise<void>}
- * @throws {ReleaseError} TRANSACTION_INCOMPLETE if owner mismatch.
+ * Errors WITHOUT `details.kind` are genuine local I/O failures (ENOENT,
+ * ENOSPC, EACCES, ...) and are rethrown unchanged — they must surface with
+ * their native message and code.
+ *
+ * @param {Error} cause - The caught error.
+ * @param {string} fallbackMessage - Message when the cause has none.
+ * @returns {ReleaseError}
  */
-async function removeLockIfExactOwner(expected, root, durabilityObserver) {
-  await assertOwnerOnDisk(expected, root);
-  await rm(lockDir(root), { recursive: true, force: true });
-  await emitDurability(durabilityObserver, { operation: 'remove-dir', path: lockDir(root) });
-  // Fsync parent directory to persist the lock removal
-  await fsyncDirObserved(join(root, '.release-skill'), durabilityObserver);
+function mapFoundationError(cause, fallbackMessage) {
+  const kind = cause?.details?.kind;
+  if (typeof kind === 'string') {
+    return new ReleaseError(mapKindToCode(kind), cause.message ?? fallbackMessage, {
+      ...cause.details,
+    });
+  }
+  if (cause instanceof TypeError) {
+    // Foundation assertOwner 上限（owner 非字符串/超长）——已由 wrapper 写前预检兜底
+    return new ReleaseError(PATH_UNSAFE, cause.message ?? fallbackMessage, {});
+  }
+  throw cause;
 }
 
 // ---------------------------------------------------------------------------
-// Internal: fsync helpers
+// Internal: lock path state & fail-closed checks
 // ---------------------------------------------------------------------------
 
 /**
- * Fsync a file by path — opens, syncs, closes.
+ * Classify the lock path state.
  *
- * @param {string} filePath
+ * @param {string} root - Repository root.
+ * @returns {Promise<'absent'|'file'|'dir'|'symlink'>}
  */
-async function fsyncFile(filePath) {
-  const fh = await open(filePath, 'r');
+async function lockPathState(root) {
+  let st;
   try {
-    await fh.sync();
-  } finally {
-    await fh.close();
+    st = await lstat(lockPath(root));
+  } catch (err) {
+    if (err.code === 'ENOENT') return 'absent';
+    throw err;
   }
+  if (st.isSymbolicLink()) return 'symlink';
+  if (st.isDirectory()) return 'dir';
+  return 'file';
 }
 
 /**
- * Fsync a directory by path.
+ * Fail closed when the lock path holds an unsafe or old-domain form.
  *
- * @param {string} dirPath
+ * - symlink → PATH_UNSAFE (same as pre-migration assertion)
+ * - directory → LOCK_MIGRATION_REQUIRED (old lock domain; never auto-migrated)
+ * - absent/file → OK (Foundation acquires / inspects the single-file lock)
+ *
+ * @param {string} root - Repository root.
+ * @returns {Promise<void>}
  */
-async function fsyncDir(dirPath) {
-  const fh = await open(dirPath, 'r');
-  try {
-    await fh.sync();
-  } finally {
-    await fh.close();
+async function assertLockPathSafe(root) {
+  const state = await lockPathState(root);
+  if (state === 'symlink') {
+    throw new ReleaseError(
+      PATH_UNSAFE,
+      '.release-skill/lock is a symlink — refusing to operate on symlinked path',
+      { path: lockPath(root) },
+    );
+  }
+  if (state === 'dir') {
+    throw new ReleaseError(
+      LOCK_MIGRATION_REQUIRED,
+      'project lock uses the old directory format; migration required',
+      { root, lockPath: lockPath(root), hint: 'confirm no command is in progress, then remove the .release-skill/lock directory' },
+    );
   }
 }
 
-// ---------------------------------------------------------------------------
-// Internal: symlink/non-directory fail-closed checks
-// ---------------------------------------------------------------------------
-
 /**
- * Assert that a path is not a symlink and, if it exists, is a directory.
- * Fails closed with PATH_UNSAFE on any violation.
+ * Assert that .release-skill exists as a real directory (not a symlink).
  *
- * @param {string} dirPath - Path to check.
- * @param {string} label - Human label for error messages.
+ * @param {string} root - Repository root.
  * @returns {Promise<void>}
- * @throws {ReleaseError} PATH_UNSAFE if symlink or non-directory.
  */
-async function assertNotSymlinkOrFile(dirPath, label) {
+async function assertReleaseSkillDirSafe(root) {
+  const releaseSkillDir = join(root, '.release-skill');
   let st;
   try {
-    st = await lstat(dirPath);
+    st = await lstat(releaseSkillDir);
   } catch (err) {
     if (err.code === 'ENOENT') return; // doesn't exist yet — OK
     throw err;
@@ -358,42 +396,112 @@ async function assertNotSymlinkOrFile(dirPath, label) {
   if (st.isSymbolicLink()) {
     throw new ReleaseError(
       PATH_UNSAFE,
-      `${label} is a symlink — refusing to operate on symlinked path`,
-      { path: dirPath },
+      '.release-skill is a symlink — refusing to operate on symlinked path',
+      { path: releaseSkillDir },
     );
   }
   if (!st.isDirectory()) {
     throw new ReleaseError(
       PATH_UNSAFE,
-      `${label} exists but is not a directory`,
-      { path: dirPath },
+      '.release-skill exists but is not a directory',
+      { path: releaseSkillDir },
     );
   }
 }
 
 /**
- * Assert that the .release-skill and lock directories are not symlinks.
- * Checks every level: .release-skill, .release-skill/lock, .release-skill/lock-audit.
+ * Assert that the audit directory is not a symlink.
  *
  * @param {string} root - Repository root.
  * @returns {Promise<void>}
  */
-async function assertLockPathsNotSymlinks(root) {
-  const releaseSkillDir = join(root, '.release-skill');
-  await assertNotSymlinkOrFile(releaseSkillDir, '.release-skill');
-  await assertNotSymlinkOrFile(lockDir(root), '.release-skill/lock');
+async function assertAuditPathNotSymlink(root) {
+  await assertReleaseSkillDirSafe(root);
+  const auditPath = auditDir(root);
+  let st;
+  try {
+    st = await lstat(auditPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  if (st.isSymbolicLink()) {
+    throw new ReleaseError(
+      PATH_UNSAFE,
+      '.release-skill/lock-audit is a symlink — refusing to operate on symlinked path',
+      { path: auditPath },
+    );
+  }
 }
 
+// ---------------------------------------------------------------------------
+// Internal: assert owner matches persisted lock record
+// ---------------------------------------------------------------------------
+
 /**
- * Assert that the audit directory is not a symlink.
+ * Parse the persisted owner string from a lock record and compare all six
+ * fields exactly with the expected owner.
+ *
+ * @param {string} persistedOwnerJson - `record.owner` from the lock file.
+ * @param {object} expected - The expected owner record.
+ * @param {string} root - Repository root.
+ * @param {string} messagePrefix - Prefix for the mismatch message.
+ * @returns {void}
+ * @throws {ReleaseError} TRANSACTION_INCOMPLETE on mismatch or corrupt record.
+ */
+function assertOwnerMatches(persistedOwnerJson, expected, root, messagePrefix) {
+  let actual;
+  try {
+    actual = JSON.parse(persistedOwnerJson);
+  } catch {
+    throw new ReleaseError(
+      TRANSACTION_INCOMPLETE,
+      'project lock owner record is corrupt',
+      { root },
+    );
+  }
+  for (const field of OWNER_FIELDS) {
+    if (actual[field] !== expected[field]) {
+      throw new ReleaseError(
+        TRANSACTION_INCOMPLETE,
+        `${messagePrefix} — field "${field}" differs`,
+        { root, field, expected: field === 'nonce' ? expected[field]?.slice(0, 8) : undefined },
+      );
+    }
+  }
+}
+
+/**
+ * Assert that the persisted lock record still belongs to `owner`.
  *
+ * @param {object} owner - The expected owner record.
  * @param {string} root - Repository root.
  * @returns {Promise<void>}
+ * @throws {ReleaseError} TRANSACTION_INCOMPLETE if lock missing or owner mismatch.
  */
-async function assertAuditPathNotSymlink(root) {
-  const releaseSkillDir = join(root, '.release-skill');
-  await assertNotSymlinkOrFile(releaseSkillDir, '.release-skill');
-  await assertNotSymlinkOrFile(auditDir(root), '.release-skill/lock-audit');
+async function assertOwned(owner, root) {
+  let inspected;
+  try {
+    inspected = await inspectFilesystemLock(root, LOCK_REL_PATH);
+  } catch (cause) {
+    if (cause?.code === 'ENOENT') {
+      // Lock domain (or .release-skill) does not exist at all — ownership lost.
+      throw new ReleaseError(
+        TRANSACTION_INCOMPLETE,
+        'project lock does not exist — ownership lost',
+        { root },
+      );
+    }
+    throw mapFoundationError(cause, 'project lock inspection failed');
+  }
+  if (!inspected.locked) {
+    throw new ReleaseError(
+      TRANSACTION_INCOMPLETE,
+      'project lock does not exist — ownership lost',
+      { root },
+    );
+  }
+  assertOwnerMatches(inspected.owner, owner, root, 'project lock owner does not match');
 }
 
 // ---------------------------------------------------------------------------
@@ -403,8 +511,10 @@ async function assertAuditPathNotSymlink(root) {
 /**
  * Acquire the project lock.
  *
- * Uses exclusive `mkdir` to atomically claim the lock. The owner record
- * is written to `.owner` and fsynced before returning.
+ * Delegates to Foundation `acquireFilesystemLock` — one exclusive create of
+ * the lock record file (temp + fsync + exclusive link + verify + directory
+ * fsync). The owner is published atomically with the lock, so there is no
+ * ownerless-lock window.
  *
  * If the lock is already held, throws `TRANSACTION_INCOMPLETE` — there is
  * no automatic stale lock breakage based on TTL.
@@ -448,20 +558,30 @@ export async function acquireProjectLock({
   }
 
   // Construct and validate the owner before touching the filesystem so a bad
-  // injected clock cannot leave a directory without an owner.
+  // injected clock cannot shape any persisted state.
   const owner = buildOwner(command, clock);
+  const ownerJson = JSON.stringify(owner);
+  if (ownerJson.length > MAX_OWNER_JSON_LENGTH) {
+    // Foundation assertOwner 上限（200 字符）；写前预检 fail-closed（G4 C.4）
+    throw new ReleaseError(
+      PATH_UNSAFE,
+      'lock owner record exceeds the 200-character limit; refusing to acquire',
+      { length: ownerJson.length },
+    );
+  }
 
-  // Symlink/non-directory fail-closed: check every path level before touching fs
+  // Symlink / old-domain fail-closed: check every path level before touching fs
   const releaseSkillDir = join(root, '.release-skill');
-  await assertLockPathsNotSymlinks(root);
+  await assertReleaseSkillDirSafe(root);
+  await assertLockPathSafe(root);
 
-  // Ensure parent directory exists (only if not already checked as non-symlink)
-  let parentExisted = false;
+  // Ensure parent directory exists (only fsync root when newly created)
+  let parentExisted = true;
   try {
     await lstat(releaseSkillDir);
-    parentExisted = true;
   } catch (err) {
     if (err.code !== 'ENOENT') throw err;
+    parentExisted = false;
   }
   if (!parentExisted) {
     await mkdir(releaseSkillDir, { recursive: true, mode: 0o700 });
@@ -470,62 +590,54 @@ export async function acquireProjectLock({
     await fsyncDirObserved(root, durabilityObserver);
   }
 
-  const dir = lockDir(root);
+  if (faultInjector) await faultInjector('after-lock-create');
 
-  // Atomic lock acquisition via mkdir. Everything after successful mkdir and
-  // before returning is inside one cleanup boundary, so any write/fsync/fault
-  // failure cannot leave an ownerless lock directory.
-  let lockCreated = false;
+  // Foundation single-file atomic lock acquisition. A failure before commit
+  // leaves nothing behind (staging is cleaned by publishFileExclusive).
+  let handle;
   try {
-    await mkdir(dir, { recursive: false, mode: 0o700 });
-    lockCreated = true;
-  } catch (err) {
-    if (err.code === 'EEXIST') {
+    handle = await acquireFilesystemLock(root, LOCK_REL_PATH, { owner: ownerJson });
+  } catch (cause) {
+    if (cause?.details?.kind === INFLIGHT_KINDS.STORE_LOCKED) {
       // Lock is held — TTL never permits automatic breakage
       throw new ReleaseError(
         TRANSACTION_INCOMPLETE,
         'project lock is already held; another command is in progress',
-        { root, lockDir: dir },
+        { root, lockPath: lockPath(root) },
       );
     }
-    throw err;
+    throw mapFoundationError(cause, 'project lock acquisition failed');
   }
 
-  const ownerFilePath = join(dir, OWNER_FILE_NAME);
-  try {
-    await emitDurability(durabilityObserver, { operation: 'create-dir', path: dir });
-    if (faultInjector) await faultInjector('after-lock-create');
-    await fsyncDirObserved(releaseSkillDir, durabilityObserver);
-
-    await writeFile(ownerFilePath, JSON.stringify(owner), { mode: 0o600, flag: 'wx' });
-    await emitDurability(durabilityObserver, { operation: 'write-file', path: ownerFilePath });
-    if (faultInjector) await faultInjector('after-owner-write');
-
-    // Fsync owner file then lock directory for durability
-    await fsyncFileObserved(ownerFilePath, durabilityObserver);
-    await fsyncDirObserved(dir, durabilityObserver);
-  } catch (writeErr) {
-    // Cleanup: remove the lock dir if owner write failed — prevents zombie lock
-    // without an owner file (which cannot be broken since break requires owner).
-    if (!lockCreated) throw writeErr;
+  // Foundation publishFileExclusive already fsynced .release-skill; record the
+  // completed boundary durability at the wrapper edge.
+  await emitDurability(durabilityObserver, { operation: 'fsync-dir', path: releaseSkillDir });
+
+  if (faultInjector) {
     try {
-      await rm(dir, { recursive: true, force: true });
-      await emitDurability(durabilityObserver, { operation: 'remove-dir', path: dir });
-      await fsyncDirObserved(releaseSkillDir, durabilityObserver);
-    } catch (cleanupErr) {
-      const incomplete = new ReleaseError(
-        TRANSACTION_INCOMPLETE,
-        'project lock acquisition failed and cleanup could not be made durable',
-        {
-          acquireErrorCode: typeof writeErr?.code === 'string' ? writeErr.code : null,
-          cleanupErrorCode: typeof cleanupErr?.code === 'string' ? cleanupErr.code : null,
-        },
-      );
-      incomplete.cause = writeErr;
-      incomplete.cleanupCause = cleanupErr;
-      throw incomplete;
+      await faultInjector('after-owner-write');
+    } catch (writeErr) {
+      // The atomic commit already happened; roll the lock back so an
+      // "acquire reported failure" never leaves a held lock behind.
+      try {
+        await releaseFilesystemLock(handle);
+        await emitDurability(durabilityObserver, { operation: 'remove-dir', path: lockPath(root) });
+        await emitDurability(durabilityObserver, { operation: 'fsync-dir', path: releaseSkillDir });
+      } catch (cleanupErr) {
+        const incomplete = new ReleaseError(
+          TRANSACTION_INCOMPLETE,
+          'project lock acquisition failed and cleanup could not be made durable',
+          {
+            acquireErrorCode: typeof writeErr?.code === 'string' ? writeErr.code : null,
+            cleanupErrorCode: typeof cleanupErr?.code === 'string' ? cleanupErr.code : null,
+          },
+        );
+        incomplete.cause = writeErr;
+        incomplete.cleanupCause = cleanupErr;
+        throw incomplete;
+      }
+      throw writeErr;
     }
-    throw writeErr;
   }
 
   return Object.freeze({
@@ -543,14 +655,14 @@ export async function acquireProjectLock({
      * @throws {ReleaseError} if ownership verification fails.
      */
     async capture(fn) {
-      await assertOwnerOnDisk(owner, root);
+      await assertOwned(owner, root);
       let fnResult;
       try {
         fnResult = await fn();
       } catch (fnErr) {
         // fn threw — still perform post-owner check (fail-closed)
         try {
-          await assertOwnerOnDisk(owner, root);
+          await assertOwned(owner, root);
         } catch {
           // Both fn error AND owner lost — fail closed with TRANSACTION_INCOMPLETE,
           // preserve the original business error as cause
@@ -566,7 +678,7 @@ export async function acquireProjectLock({
         throw fnErr;
       }
       // fn succeeded — post-owner check
-      await assertOwnerOnDisk(owner, root);
+      await assertOwned(owner, root);
       return fnResult;
     },
 
@@ -577,18 +689,25 @@ export async function acquireProjectLock({
      * @throws {ReleaseError} TRANSACTION_INCOMPLETE if ownership lost.
      */
     async assertOwner() {
-      return assertOwnerOnDisk(owner, root);
+      return assertOwned(owner, root);
     },
 
     /**
-     * Release the lock. Only succeeds if the persisted owner matches exactly.
-     * After removal, fsyncs the parent .release-skill directory for durability.
+     * Release the lock. Only succeeds if the persisted record still matches
+     * the token and identity captured at acquire. Foundation `unlinkSame`
+     * fsyncs `.release-skill` as part of removal.
      *
      * @returns {Promise<void>}
-     * @throws {ReleaseError} TRANSACTION_INCOMPLETE if owner mismatch.
+     * @throws {ReleaseError} TRANSACTION_INCOMPLETE if token/owner mismatch.
      */
     async release() {
-      return removeLockIfExactOwner(owner, root, durabilityObserver);
+      try {
+        await releaseFilesystemLock(handle);
+      } catch (cause) {
+        throw mapFoundationError(cause, 'project lock release failed — token or owner does not match');
+      }
+      await emitDurability(durabilityObserver, { operation: 'remove-dir', path: lockPath(root) });
+      await emitDurability(durabilityObserver, { operation: 'fsync-dir', path: releaseSkillDir });
     },
   });
 }
@@ -596,9 +715,10 @@ export async function acquireProjectLock({
 /**
  * Break a project lock by force.
  *
- * Requires the exact owner record to match what is persisted on disk.
- * Writes an audit record to `.release-skill/lock-audit/` before removing
- * the lock directory.
+ * Requires the exact owner record to match what is persisted in the lock
+ * record. Writes an audit record to `.release-skill/lock-audit/` before
+ * recovering (removing) the lock file via Foundation `recoverFilesystemLock`
+ * (explicit operator recovery — no age/PID/liveness inference).
  *
  * @param {object} options
  * @param {string} options.root - Repository root (absolute).
@@ -627,45 +747,26 @@ export async function breakProjectLock({ root, expectedOwner, reason, clock, dur
   const brokenAt = clock ? clock() : new Date().toISOString();
   assertIsoTimestamp(brokenAt, 'clock result');
 
-  // Symlink/non-directory fail-closed check before reading owner
-  await assertLockPathsNotSymlinks(root);
-
-  // Read persisted owner
-  let raw;
-  try {
-    raw = await readFile(ownerPath(root), 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      throw new ReleaseError(
-        TRANSACTION_INCOMPLETE,
-        'no project lock to break — lock directory does not exist',
-        { root },
-      );
-    }
-    throw err;
-  }
-
-  let actualOwner;
-  try {
-    actualOwner = JSON.parse(raw);
-  } catch {
+  // Symlink / old-domain / absent fail-closed check before reading the lock record
+  await assertReleaseSkillDirSafe(root);
+  await assertLockPathSafe(root);
+  if ((await lockPathState(root)) === 'absent') {
     throw new ReleaseError(
       TRANSACTION_INCOMPLETE,
-      'project lock owner file is corrupt — cannot break safely',
+      'no project lock to break — lock file does not exist',
       { root },
     );
   }
 
-  // Exact owner match: all six fields must match
-  for (const field of OWNER_FIELDS) {
-    if (actualOwner[field] !== expectedOwner[field]) {
-      throw new ReleaseError(
-        TRANSACTION_INCOMPLETE,
-        `break-lock rejected: expectedOwner does not match persisted owner (field: ${field})`,
-        { root, field },
-      );
-    }
+  let inspected;
+  try {
+    inspected = await inspectFilesystemLock(root, LOCK_REL_PATH);
+  } catch (cause) {
+    throw mapFoundationError(cause, 'project lock inspection failed');
   }
+  assertOwnerMatches(inspected.owner, expectedOwner, root, 'break-lock rejected: expectedOwner does not match persisted owner');
+
+  const actualOwner = JSON.parse(inspected.owner); // 已通过 assertOwnerMatches 校验
 
   // Check audit path is not a symlink before writing
   await assertAuditPathNotSymlink(root);
@@ -688,7 +789,7 @@ export async function breakProjectLock({ root, expectedOwner, reason, clock, dur
     breakerHost: hostname(),
   });
 
-  // Write audit evidence before removing lock
+  // Write audit evidence before recovering the lock
   const auditDirectory = auditDir(root);
   await mkdir(auditDirectory, { recursive: true, mode: 0o700 });
   await emitDurability(durabilityObserver, { operation: 'create-dir', path: auditDirectory });
@@ -704,12 +805,21 @@ export async function breakProjectLock({ root, expectedOwner, reason, clock, dur
   await fsyncFileObserved(auditFilePath, durabilityObserver);
   await fsyncDirObserved(auditDirectory, durabilityObserver);
 
-  // Remove the lock directory
-  await rm(lockDir(root), { recursive: true, force: true });
-  await emitDurability(durabilityObserver, { operation: 'remove-dir', path: lockDir(root) });
-
-  // Fsync parent after lock removal
-  await fsyncDirObserved(join(root, '.release-skill'), durabilityObserver);
+  // Explicit operator recovery: digest must still match the inspected record
+  // (TOCTOU fail-closed — the lock may not have changed between inspect and recover).
+  try {
+    await recoverFilesystemLock(root, LOCK_REL_PATH, {
+      expectedTokenDigest: inspected.tokenDigest,
+      confirmAbandoned: true,
+    });
+  } catch (cause) {
+    throw mapFoundationError(cause, 'project lock break failed — lock changed after inspection');
+  }
+
+  // Foundation unlinkSame fsynced .release-skill as part of removal; record
+  // the completed boundary durability at the wrapper edge.
+  await emitDurability(durabilityObserver, { operation: 'remove-dir', path: lockPath(root) });
+  await emitDurability(durabilityObserver, { operation: 'fsync-dir', path: join(root, '.release-skill') });
 
   return auditRecord;
 }