skill-family-harness-node 0.8.2 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.8.3 locale=en baseline=sha256:449943bedf3698888fec4dcb09a0460f337b9406d5258946a3d3ffcd23143b8d -->
+## [0.8.3] - 2026-08-23
+
+Path containment now tolerates one exact anchor-removal race while preserving fail-closed escape checks.
+
+### Changed
+
+- A second ENOENT and every non-ENOENT failure remain closed; symlink swaps, out-of-root targets, and all existing containment checks remain rejected.
+- Keeps the hook private to the paths module test surface and adds no public export, general retry policy, lock layer, ledger, or runner.
+- Moves the package version to 0.8.3 together with Contracts and Engineering Kit.
+
+### Fixed
+
+- When realpath of the selected existing anchor fails with ENOENT because another process removed it, resolveContained recomputes the deepest existing ancestor exactly once.
+
+### Upgrade Notes
+
+Consumers must pin all three Foundation packages to exactly 0.8.3. Concurrent lock acquisition can now survive the current owner removing the selected lock-file anchor; no Harness API migration is required.
+<!-- release-skill:changelog:end version=0.8.3 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.8.2 locale=en baseline=sha256:af051a6925c7d1f46bef6fbe367aceea8685b4a916629af4e69334e73014e3a7 -->
 ## [0.8.2] - 2026-08-23
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.8.3 locale=zh-CN baseline=sha256:b84695a286aca7c1a9f90844f8682cde07d32276cebc11583568bc5ef11753fc -->
+## [0.8.3] - 2026-08-23
+
+路径收容现在可处理一次精确的锚点并发删除，同时保持越界检查失败关闭。
+
+### 变更
+
+- 第二次 ENOENT 与所有非 ENOENT 错误仍失败关闭；符号链接替换、根目录外目标和既有收容检查仍全部拒绝。
+- 测试钩子只留在 paths 模块的测试表面，不新增公共导出、通用重试策略、锁层、账本或 runner。
+- 包版本与 Contracts、Engineering Kit 一同升至 0.8.3。
+
+### 修复
+
+- 当另一进程删除已选锚点，导致该锚点的 realpath 返回 ENOENT 时，resolveContained 仅重新计算一次最深既存祖先。
+
+### 升级说明
+
+消费者必须把三个 Foundation 包精确锁定到 0.8.3。并发获取锁时，即使当前持有者删除已选锁文件锚点，也能完成一次安全重求；Harness API 无需迁移。
+<!-- release-skill:changelog:end version=0.8.3 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.8.2 locale=zh-CN baseline=sha256:748d79d51dcabe6193332e60ec69a6eb26fd914ad3555f6e924b78db71016192 -->
 ## [0.8.2] - 2026-08-23
 

package/README.md

@@ -4,28 +4,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.8.2 -->
+<!-- release-skill:release-version: 0.8.3 -->
 
 The **single default Node implementation** of the Contracts mechanism protocol. This is a thin runtime: it only implements the mechanism protocol, introduces no business semantics, and does not provide a second-language implementation.
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.8.2** (2026-08-23)
+**0.8.3** (2026-08-23)
 
-The fixed candidate mechanism bridge now exposes the existing strict reader through read-file-strict.
+Path containment now tolerates one exact anchor-removal race while preserving fail-closed escape checks.
 
-**Added**
+**Changed**
 
-- Adds read-file-strict to invokeFoundationMechanism with closed root, path, encoding, and expectedSha256 parameters.
-- Returns UTF-8 content as a string and binary content in the standard JSON-safe Buffer shape.
+- A second ENOENT and every non-ENOENT failure remain closed; symlink swaps, out-of-root targets, and all existing containment checks remain rejected.
+- Keeps the hook private to the paths module test surface and adds no public export, general retry policy, lock layer, ledger, or runner.
+- Moves the package version to 0.8.3 together with Contracts and Engineering Kit.
 
-**Changed**
+**Fixed**
 
-- Delegates containment, file reading, digest verification, and failure classification directly to readFileStrict; no second read algorithm is introduced.
-- Moves the package version to 0.8.2 together with Contracts and Engineering Kit.
+- When realpath of the selected existing anchor fails with ENOENT because another process removed it, resolveContained recomputes the deepest existing ancestor exactly once.
 
 **Upgrade Notes**
 
-Candidate consumers must pin all three Foundation packages to exactly 0.8.2 and rebuild their managed Bundle. Direct calls retain SFC2004 details.kind failures; the JSON CLI continues to promise only exit code 0 for success and 2 for rejection.
+Consumers must pin all three Foundation packages to exactly 0.8.3. Concurrent lock acquisition can now survive the current owner removing the selected lock-file anchor; no Harness API migration is required.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -39,14 +39,14 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 ## Installation and Minimal Example
 
 ```sh
-npm install skill-family-harness-node@0.8.2
+npm install skill-family-harness-node@0.8.3
 npm info skill-family-harness-node --help
 ```
 
 The minimal example shows validating a contract document inside Node:
 
 ```js
-// Run from an empty directory: npm install skill-family-harness-node@0.8.2
+// Run from an empty directory: npm install skill-family-harness-node@0.8.3
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/README.zh-CN.md

@@ -5,28 +5,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.8.2 -->
+<!-- release-skill:release-version: 0.8.3 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.8.2** (2026-08-23)
+**0.8.3** (2026-08-23)
 
-固定的候选机制桥接新增 read-file-strict，直接公开既有严格读取机制。
+路径收容现在可处理一次精确的锚点并发删除，同时保持越界检查失败关闭。
 
-**新增**
+**变更**
 
-- invokeFoundationMechanism 新增 read-file-strict；参数闭合为 root、path、encoding 和 expectedSha256。
-- UTF-8 内容返回字符串，二进制内容返回标准的 JSON 安全 Buffer 形态。
+- 第二次 ENOENT 与所有非 ENOENT 错误仍失败关闭；符号链接替换、根目录外目标和既有收容检查仍全部拒绝。
+- 测试钩子只留在 paths 模块的测试表面，不新增公共导出、通用重试策略、锁层、账本或 runner。
+- 包版本与 Contracts、Engineering Kit 一同升至 0.8.3。
 
-**变更**
+**修复**
 
-- 路径收容、文件读取、摘要复验和失败分类全部转发给 readFileStrict，不新增第二套读取算法。
-- 包版本与 Contracts、Engineering Kit 一同升至 0.8.2。
+- 当另一进程删除已选锚点，导致该锚点的 realpath 返回 ENOENT 时，resolveContained 仅重新计算一次最深既存祖先。
 
 **升级说明**
 
-候选消费者必须把三个 Foundation 包精确锁定到 0.8.2，再重建受管 Bundle。直接调用继续返回 SFC2004 与 details.kind；JSON CLI 只承诺成功退出码 0 和拒绝退出码 2。
+消费者必须把三个 Foundation 包精确锁定到 0.8.3。并发获取锁时，即使当前持有者删除已选锁文件锚点，也能完成一次安全重求；Harness API 无需迁移。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -40,14 +40,14 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 ## 安装和最小示例
 
 ```sh
-npm install skill-family-harness-node@0.8.2
+npm install skill-family-harness-node@0.8.3
 npm info skill-family-harness-node --help
 ```
 
 最小示例演示在 Node 内校验一份契约文档：
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node@0.8.2
+// 从空目录运行：npm install skill-family-harness-node@0.8.3
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@pnpm/lockfile.fs": "1001.1.35",
     "ipaddr.js": "2.5.0",
-    "skill-family-contracts": "0.8.2",
+    "skill-family-contracts": "0.8.3",
     "yaml": "2.9.0"
   },
   "description": "Thin Node.js mechanism runtime for Skill Family engineering contracts.",
@@ -45,7 +45,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.8.3.yaml

@@ -0,0 +1,23 @@
+version: 0.8.3
+date: 2026-08-23
+locales:
+  en:
+    summary: Path containment now tolerates one exact anchor-removal race while preserving fail-closed escape checks.
+    changes:
+      fixed:
+        - When realpath of the selected existing anchor fails with ENOENT because another process removed it, resolveContained recomputes the deepest existing ancestor exactly once.
+      changed:
+        - A second ENOENT and every non-ENOENT failure remain closed; symlink swaps, out-of-root targets, and all existing containment checks remain rejected.
+        - Keeps the hook private to the paths module test surface and adds no public export, general retry policy, lock layer, ledger, or runner.
+        - Moves the package version to 0.8.3 together with Contracts and Engineering Kit.
+    upgradeNotes: Consumers must pin all three Foundation packages to exactly 0.8.3. Concurrent lock acquisition can now survive the current owner removing the selected lock-file anchor; no Harness API migration is required.
+  zh-CN:
+    summary: 路径收容现在可处理一次精确的锚点并发删除，同时保持越界检查失败关闭。
+    changes:
+      fixed:
+        - 当另一进程删除已选锚点，导致该锚点的 realpath 返回 ENOENT 时，resolveContained 仅重新计算一次最深既存祖先。
+      changed:
+        - 第二次 ENOENT 与所有非 ENOENT 错误仍失败关闭；符号链接替换、根目录外目标和既有收容检查仍全部拒绝。
+        - 测试钩子只留在 paths 模块的测试表面，不新增公共导出、通用重试策略、锁层、账本或 runner。
+        - 包版本与 Contracts、Engineering Kit 一同升至 0.8.3。
+    upgradeNotes: 消费者必须把三个 Foundation 包精确锁定到 0.8.3。并发获取锁时，即使当前持有者删除已选锁文件锚点，也能完成一次安全重求；Harness API 无需迁移。

package/src/paths.mjs

@@ -32,6 +32,13 @@ import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
 const WINDOWS_DRIVE_PATTERN = /^[A-Za-z]:/;
 const WINDOWS_UNC_PATTERN = /^\\\\/;
 const POSIX_UNC_PATTERN = /^\/\//;
+const ANCHOR_REALPATH_ATTEMPTS = 2;
+
+let testHooks = null;
+
+async function runTestHook(name, context) {
+  if (typeof testHooks?.[name] === "function") await testHooks[name](context);
+}
 
 /**
  * Classifies one candidate relative path without touching the filesystem.
@@ -143,7 +150,13 @@ async function deepestExistingAncestor(rootReal, absPath) {
     try {
       await lstat(current);
       return { anchor: current, missing };
-    } catch {
+    } catch (cause) {
+      if (cause?.code !== "ENOENT" && cause?.code !== "ENOTDIR") {
+        throw mechanismError(
+          HARNESS_ERROR_KINDS.READ_FAILED,
+          `path ancestor cannot be inspected: ${cause?.code ?? "unknown"}`,
+        );
+      }
       missing.unshift(path.basename(current));
       const parent = path.dirname(current);
       if (parent === current) break;
@@ -158,6 +171,31 @@ async function deepestExistingAncestor(rootReal, absPath) {
   );
 }
 
+async function canonicalAnchor(rootReal, resolved, relPath) {
+  for (let attempt = 0; attempt < ANCHOR_REALPATH_ATTEMPTS; attempt += 1) {
+    const { anchor, missing } = await deepestExistingAncestor(rootReal, resolved);
+    await runTestHook("beforeAnchorRealpath", { anchor, attempt });
+    try {
+      return { anchorReal: await realpath(anchor), missing };
+    } catch (cause) {
+      // An existing lock or staging file can be removed by its owner between
+      // lstat() and realpath(). Recompute the ancestor once for that exact
+      // disappearance race; every other error remains fail-closed.
+      if (cause?.code === "ENOENT" && attempt + 1 < ANCHOR_REALPATH_ATTEMPTS) continue;
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
+        "anchor directory vanished during canonical resolution",
+        { input: relPath, code: cause?.code },
+      );
+    }
+  }
+  throw mechanismError(
+    HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
+    "anchor directory vanished during canonical resolution",
+    { input: relPath },
+  );
+}
+
 /**
  * Resolves `relPath` against `root` and proves the target stays inside.
  * Returns the absolute, lexically resolved path (strictly inside the root).
@@ -221,17 +259,7 @@ export async function resolveContained(root, relPath) {
 
   // Escape class 3: canonical resolution (any intermediate symlink chain)
   // must stay inside the canonical root.
-  const { anchor, missing } = await deepestExistingAncestor(rootReal, resolved);
-  let anchorReal;
-  try {
-    anchorReal = await realpath(anchor);
-  } catch {
-    throw mechanismError(
-      HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
-      "anchor directory vanished during canonical resolution",
-      { input: relPath },
-    );
-  }
+  const { anchorReal, missing } = await canonicalAnchor(rootReal, resolved, relPath);
   if (!insideOrEqualRoot(rootReal, anchorReal)) {
     throw mechanismError(
       HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
@@ -250,6 +278,14 @@ export async function resolveContained(root, relPath) {
   return resolved;
 }
 
+/** Test-only hooks. Deliberately not re-exported from the package index. */
+export function __setPathsTestHooks(hooks) {
+  if (hooks !== null && (!hooks || typeof hooks !== "object" || Array.isArray(hooks))) {
+    throw new TypeError("paths test hooks must be an object or null");
+  }
+  testHooks = hooks;
+}
+
 /**
  * Contained read. Returns the file content as a Buffer (utf8 string when
  * encoding is "utf8"). Missing resources surface as SFC2004 with the stable