skill-family-harness-node 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.13.0 locale=en baseline=sha256:ba0667eb4b4805aafc2423cd79c04df3c835b8ae9bb07391867175f6ad96c36b -->
+## [0.13.0] - 2026-08-26
+
+Harness 0.13.0 is a source candidate for complete bound-tree observations and optional subprocess output limits.
+
+### Added
+
+- Adds observeFilesystemTree({ root, rootBinding }) as a public candidate entry for fresh private tree facts, including file bytes and POSIX mode observations.
+
+### Changed
+
+- Extends superviseProcess with independent stdout/stderr byte limits using the existing termination path. Equal-to-limit output is allowed; uncapped behavior remains compatible.
+
+### Upgrade Notes
+
+Pin Contracts and Harness together. Tree observation does not apply payload acceptance policy or promise a transaction snapshot. Candidate preparation is not publication.
+<!-- release-skill:changelog:end version=0.13.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.12.0 locale=en baseline=sha256:0074df3a947706f6cd6d8593968a348cd4d3f38d8f2bf75f15a04c8183d76618 -->
 ## [0.12.0] - 2026-08-26
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,24 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.13.0 locale=zh-CN baseline=sha256:1356b2ecff87da4a8bbe5bc04980b125ddf181873ff2b536be87a2e246b59609 -->
+## [0.13.0] - 2026-08-26
+
+Harness 0.13.0 源码候选增加完整绑定树观察与可选子进程输出上限。
+
+### 新增
+
+- 新增公开候选入口 observeFilesystemTree({ root, rootBinding })，每次读取私有树事实，包含文件字节与 POSIX 模式观察。
+
+### 变更
+
+- 为 superviseProcess 增加 stdout/stderr 独立字节上限，复用既有终止路径；等于上限允许，未设置上限保持旧行为。
+
+### 升级说明
+
+Contracts 与 Harness 须精确锁步。树观察不执行载荷接受政策，也不承诺事务快照。候选准备不代表发布完成。
+<!-- release-skill:changelog:end version=0.13.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.12.0 locale=zh-CN baseline=sha256:2e7db41a08c30d9e0bdc16b4cd27853104ef79dc02f7e9925a1383a6546f5111 -->
 ## [0.12.0] - 2026-08-26
 

package/README.md

@@ -4,22 +4,26 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.12.0 -->
+<!-- release-skill:release-version: 0.13.0 -->
 
 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.12.0** (2026-08-26)
+**0.13.0** (2026-08-26)
 
-Harness 0.12.0 joins the lockstep Foundation release with its existing process and filesystem mechanisms unchanged.
+Harness 0.13.0 is a source candidate for complete bound-tree observations and optional subprocess output limits.
+
+**Added**
+
+- Adds observeFilesystemTree({ root, rootBinding }) as a public candidate entry for fresh private tree facts, including file bytes and POSIX mode observations.
 
 **Changed**
 
-- Pins skill-family-contracts to 0.12.0 for the five-host verification extension implemented by Engineering Kit.
+- Extends superviseProcess with independent stdout/stderr byte limits using the existing termination path. Equal-to-limit output is allowed; uncapped behavior remains compatible.
 
 **Upgrade Notes**
 
-No new Harness API or runtime behavior is introduced. Existing process supervision, raw-byte sinks, bound reads, and digest mechanisms remain the shared implementation; host-specific protocol rules belong to Engineering Kit.
+Pin Contracts and Harness together. Tree observation does not apply payload acceptance policy or promise a transaction snapshot. Candidate preparation is not publication.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -32,15 +36,17 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 
 ## Installation and Minimal Example
 
+Version 0.13.0 is not published. The registry command below is for use after publication; this iteration installs the three local candidate tarballs in an isolated directory.
+
 ```sh
-npm install skill-family-harness-node@0.12.0
+npm install skill-family-harness-node@0.13.0
 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.12.0
+// Run from an empty directory: npm install skill-family-harness-node@0.13.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -218,3 +224,9 @@ Mechanism failures uniformly throw `SFC2004` (EXECUTION_FAILED), with `details.k
 - Package-local source: `src/*.mjs`.
 - Package-local candidate source: `candidate/quickstart-profile.mjs`; canonical public import: `skill-family-harness-node/quickstart-profile`; historical migration alias: `skill-family-harness-node/candidate/quickstart-profile`.
 <!-- agent-quick-reference:end -->
+
+## Complete Plugin Candidate
+
+The candidate observeFilesystemTree({ root, rootBinding }) reads complete tree facts. Existing superviseProcess accepts optional per-stream raw-byte caps. Observing a payload does not accept it.
+
+Version 0.13.0 is a local source candidate and is not published. Consume the three locally verified tarballs; a version marker, unit test or successful install is not complete host qualification or release approval.

package/README.zh-CN.md

@@ -5,22 +5,26 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.12.0 -->
+<!-- release-skill:release-version: 0.13.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.12.0** (2026-08-26)
+**0.13.0** (2026-08-26)
 
-Harness 0.12.0 随 Foundation 三包锁步升级，既有进程与文件系统机制保持不变。
+Harness 0.13.0 源码候选增加完整绑定树观察与可选子进程输出上限。
+
+**新增**
+
+- 新增公开候选入口 observeFilesystemTree({ root, rootBinding })，每次读取私有树事实，包含文件字节与 POSIX 模式观察。
 
 **变更**
 
-- 将 skill-family-contracts 精确依赖更新为 0.12.0，支持 Engineering Kit 的五平台验证扩展。
+- 为 superviseProcess 增加 stdout/stderr 独立字节上限，复用既有终止路径；等于上限允许，未设置上限保持旧行为。
 
 **升级说明**
 
-本版本不新增 Harness API，也不改变运行行为。进程监督、原始字节输出、绑定读取和摘要继续复用既有机制；宿主专属的协议规则由 Engineering Kit 实现。
+Contracts 与 Harness 须精确锁步。树观察不执行载荷接受政策，也不承诺事务快照。候选准备不代表发布完成。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -33,15 +37,17 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 
 ## 安装和最小示例
 
+0.13.0 尚未发布。下面的 registry 安装命令供发布后使用；本轮验证应在隔离目录安装三个本地候选 tarball。
+
 ```sh
-npm install skill-family-harness-node@0.12.0
+npm install skill-family-harness-node@0.13.0
 npm info skill-family-harness-node --help
 ```
 
 最小示例演示在 Node 内校验一份契约文档：
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node@0.12.0
+// 从空目录运行：npm install skill-family-harness-node@0.13.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -218,3 +224,9 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 - 包内源：`src/*.mjs`。
 - 包内 Candidate 源：`candidate/quickstart-profile.mjs`；规范公共导入：`skill-family-harness-node/quickstart-profile`；历史迁移别名：`skill-family-harness-node/candidate/quickstart-profile`。
 <!-- agent-quick-reference:end -->
+
+## 完整插件候选能力
+
+新增候选 observeFilesystemTree({ root, rootBinding }) 读取完整树事实；既有 superviseProcess 支持可选每流原始字节上限。观察完成不等于接受载荷。
+
+0.13.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball，不能把版本标记、单元测试或安装成功当作完整宿主资格与发布批准。

package/SECURITY.md

@@ -4,10 +4,10 @@
 
 | 版本 | 安全支持状态 |
 | --- | --- |
-| 0.1.x | 当前维护线：接受安全报告 |
+| 0.13.x | 当前维护线：接受安全报告 |
 | 0.0.0 | 未发布的内部骨架版本，不在公开支持范围 |
 
-安全修复只承诺在最新的 0.1.x 线上提供；更早版本不回移修复。
+安全修复只承诺在最新的 0.13.x 线上提供；更早版本不回移修复。
 
 ## 报告漏洞
 

package/package.json

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

package/release-notes/0.13.0.yaml

@@ -0,0 +1,19 @@
+version: 0.13.0
+date: 2026-08-26
+locales:
+  en:
+    summary: Harness 0.13.0 is a source candidate for complete bound-tree observations and optional subprocess output limits.
+    changes:
+      added:
+        - Adds observeFilesystemTree({ root, rootBinding }) as a public candidate entry for fresh private tree facts, including file bytes and POSIX mode observations.
+      changed:
+        - Extends superviseProcess with independent stdout/stderr byte limits using the existing termination path. Equal-to-limit output is allowed; uncapped behavior remains compatible.
+    upgradeNotes: Pin Contracts and Harness together. Tree observation does not apply payload acceptance policy or promise a transaction snapshot. Candidate preparation is not publication.
+  zh-CN:
+    summary: Harness 0.13.0 源码候选增加完整绑定树观察与可选子进程输出上限。
+    changes:
+      added:
+        - 新增公开候选入口 observeFilesystemTree({ root, rootBinding })，每次读取私有树事实，包含文件字节与 POSIX 模式观察。
+      changed:
+        - 为 superviseProcess 增加 stdout/stderr 独立字节上限，复用既有终止路径；等于上限允许，未设置上限保持旧行为。
+    upgradeNotes: Contracts 与 Harness 须精确锁步。树观察不执行载荷接受政策，也不承诺事务快照。候选准备不代表发布完成。

package/src/bound-read.mjs

@@ -161,7 +161,7 @@ export async function createFilesystemRootBinding(root) {
   }
 }
 
-function assertRelativePath(relPath) {
+export function assertRelativePath(relPath) {
   if (typeof relPath !== "string" || relPath.length === 0 || relPath.includes("\0") ||
       relPath.includes("\\") || path.posix.isAbsolute(relPath)) {
     throw mechanismError(HARNESS_ERROR_KINDS.INVALID_PATH, "bound read path is not a contained relative path");
@@ -269,6 +269,7 @@ export async function readFileBound(root, relPath, { rootBinding, encoding, expe
       sha256,
       bytes: bytes.length,
       mode: Number(native.leafMode),
+      statMode: Number(native.statMode),
       rootMode: captured.identity.mode,
     });
   } finally {

package/src/filesystem-observation.mjs

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { digestDocument } from "skill-family-contracts";
+import { digestBytes } from "./closure.mjs";
+import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+import { assertRelativePath, createFilesystemRootBinding } from "./bound-read.mjs";
+import { loadNativeBoundReadAddon } from "./native/loader.mjs";
+
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+
+/**
+ * Observe every directory and regular-file member of one already bound tree.
+ * Native code opens each member relative to the root and supplies its bytes
+ * and descriptor facts; this layer only derives the public contract shape.
+ */
+export async function observeFilesystemTree({ root, rootBinding } = {}) {
+  if (typeof root !== "string" || !path.isAbsolute(root) || path.normalize(root) !== root) {
+    throw new TypeError("observeFilesystemTree: root must be a normalized absolute path");
+  }
+  if (!rootBinding || typeof rootBinding !== "object" ||
+      typeof rootBinding.digest !== "string" || !SHA256_PATTERN.test(rootBinding.digest)) {
+    throw new TypeError("observeFilesystemTree: rootBinding is required");
+  }
+  const startBinding = await createFilesystemRootBinding(root);
+  if (startBinding.digest !== rootBinding.digest) {
+    throw mechanismError(HARNESS_ERROR_KINDS.UNSAFE_STATE_ENTRY, "approved root binding does not match the current root", {
+      boundReadDisposition: "boundary-indeterminate",
+    });
+  }
+  const { addon } = await loadNativeBoundReadAddon();
+  if (typeof addon.observeFilesystemTreeNative !== "function") {
+    throw mechanismError(HARNESS_ERROR_KINDS.UNSUPPORTED_PLATFORM, "native filesystem observation is unavailable in this prebuild");
+  }
+  let native;
+  try {
+    native = addon.observeFilesystemTreeNative(root);
+  } catch (cause) {
+    throw mechanismError(HARNESS_ERROR_KINDS.READ_FAILED, "filesystem tree observation failed", {
+      cause: cause?.message ?? "unknown",
+    });
+  }
+  const endBinding = await createFilesystemRootBinding(root);
+  if (endBinding.digest !== rootBinding.digest || native.rootDevice === undefined || native.rootInode === undefined ||
+      Number(native.rootMode) !== Number.parseInt(native.rootMode, 10)) {
+    throw mechanismError(HARNESS_ERROR_KINDS.UNSAFE_STATE_ENTRY, "root identity changed during filesystem tree observation", {
+      boundReadDisposition: "boundary-indeterminate",
+    });
+  }
+  const paths = new Set();
+  const members = Array.from(native.members ?? [], (member) => {
+    assertRelativePath(member.path);
+    const alias = member.path.toLowerCase();
+    if (paths.has(alias)) throw mechanismError(HARNESS_ERROR_KINDS.INVALID_PATH, "filesystem tree contains duplicate or case-alias member paths");
+    paths.add(alias);
+    if (member.type === "directory") {
+      return { path: member.path, type: "directory", statMode: Number(member.statMode) };
+    }
+    const bytes = Buffer.from(member.content);
+    return {
+      path: member.path,
+      type: "file",
+      sha256: digestBytes(bytes),
+      bytes: bytes.length,
+      statMode: Number(member.statMode),
+      contentBase64: bytes.toString("base64"),
+    };
+  }).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+  return Object.freeze({
+    schemaVersion: 1,
+    kind: "skill-family.filesystem-tree-observation",
+    rootBinding,
+    members: Object.freeze(members.map((member) => Object.freeze(member))),
+    membersDigest: digestDocument(members),
+  });
+}

package/src/index.mjs

@@ -49,6 +49,10 @@ export { HarnessError, HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs"
 
 export { classifyPathInput, resolveContained, readFileContained } from "./paths.mjs";
 
+// Complete bound-tree facts for plugin verification. The native reader owns
+// descriptor-relative traversal and same-descriptor fstat/read checks.
+export { observeFilesystemTree } from "./filesystem-observation.mjs";
+
 // Strict contained read (FG-1): no-follow, regular-file identity assertion,
 // and a post-read sha256 digest receipt for existing authority files.
 export { readFileStrict } from "./strict-read.mjs";

package/src/native/assemble-stable-prebuild.mjs

@@ -16,7 +16,7 @@ const PLATFORMS = Object.freeze({
   "linux-arm64-gnu": { os: "linux", arch: "arm64", libc: "glibc" },
   "linux-x64-gnu": { os: "linux", arch: "x64", libc: "glibc" },
 });
-const EXPORTS = Object.freeze(["closeParentDirectory", "openParentDirectory", "platform", "readFileBoundNative", "renameDirectoryNoReplace"]);
+const EXPORTS = Object.freeze(["closeParentDirectory", "observeFilesystemTreeNative", "openParentDirectory", "platform", "readFileBoundNative", "renameDirectoryNoReplace"]);
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 const bindingGypSha256 = sha256(readFileSync(BINDING_GYP));
 

package/src/native/bound_read.c

@@ -11,6 +11,7 @@
 #include <string.h>
 #include <sys/stat.h>
 #include <sys/types.h>
+#include <dirent.h>
 #include <unistd.h>
 
 #if defined(__APPLE__)
@@ -254,6 +255,8 @@ static napi_value ReadFileBoundNative(napi_env env, napi_callback_info info) {
   NAPI_OK(napi_set_named_property(env, result, "rootMode", value), "cannot set root mode");
   NAPI_OK(napi_create_int64(env, (int64_t)(leaf_stat.st_mode & 0777), &value), "cannot encode leaf mode");
   NAPI_OK(napi_set_named_property(env, result, "leafMode", value), "cannot set leaf mode");
+  NAPI_OK(napi_create_int64(env, (int64_t)leaf_stat.st_mode, &value), "cannot encode leaf stat mode");
+  NAPI_OK(napi_set_named_property(env, result, "statMode", value), "cannot set leaf stat mode");
   char decimal[64];
   snprintf(decimal, sizeof(decimal), "%llu", (unsigned long long)root_stat.st_dev);
   if (set_string(env, result, "rootDevice", decimal) == NULL) return NULL;
@@ -418,10 +421,151 @@ static napi_value RenameDirectoryNoReplace(napi_env env, napi_callback_info info
   return result;
 }
 
+/* A complete bound-tree observation is deliberately implemented beside the
+ * existing descriptor-relative reader.  Every regular member is opened with
+ * openat(O_NOFOLLOW), fstat'd on that descriptor, read from that descriptor,
+ * and fstat'd again before the descriptor is closed.  JavaScript only receives
+ * the bytes and facts from that one descriptor; it never supplements them
+ * with path-based lstat calls. */
+static int same_member_stat(const struct stat *before, const struct stat *after) {
+  return before->st_dev == after->st_dev && before->st_ino == after->st_ino &&
+    before->st_mode == after->st_mode && before->st_nlink == after->st_nlink &&
+    before->st_size == after->st_size && before->st_mtime == after->st_mtime &&
+    before->st_ctime == after->st_ctime;
+}
+
+static int set_int64(napi_env env, napi_value object, const char *name, int64_t value) {
+  napi_value encoded;
+  if (napi_create_int64(env, value, &encoded) != napi_ok ||
+      napi_set_named_property(env, object, name, encoded) != napi_ok) {
+    napi_throw_error(env, NULL, "cannot encode filesystem observation fact");
+    return 0;
+  }
+  return 1;
+}
+
+static int set_member_string(napi_env env, napi_value object, const char *name, const char *value) {
+  return set_string(env, object, name, value) != NULL;
+}
+
+static int append_directory_member(napi_env env, napi_value members, uint32_t *count,
+                                   const char *relative, const struct stat *st) {
+  napi_value member;
+  if (napi_create_object(env, &member) != napi_ok) { napi_throw_error(env, NULL, "cannot create directory observation"); return 0; }
+  if (!set_member_string(env, member, "path", relative) ||
+      !set_member_string(env, member, "type", "directory") ||
+      !set_int64(env, member, "statMode", (int64_t)st->st_mode)) return 0;
+  if (napi_set_element(env, members, (*count)++, member) != napi_ok) { napi_throw_error(env, NULL, "cannot append directory observation"); return 0; }
+  return 1;
+}
+
+static int append_file_member(napi_env env, napi_value members, uint32_t *count,
+                              const char *relative, const struct stat *st,
+                              const unsigned char *bytes, size_t length) {
+  napi_value member, buffer;
+  if (napi_create_object(env, &member) != napi_ok) { napi_throw_error(env, NULL, "cannot create file observation"); return 0; }
+  if (!set_member_string(env, member, "path", relative) ||
+      !set_member_string(env, member, "type", "file") ||
+      !set_int64(env, member, "statMode", (int64_t)st->st_mode) ||
+      !set_int64(env, member, "bytes", (int64_t)length)) return 0;
+  if (napi_create_buffer_copy(env, length, bytes, NULL, &buffer) != napi_ok ||
+      napi_set_named_property(env, member, "content", buffer) != napi_ok ||
+      napi_set_element(env, members, (*count)++, member) != napi_ok) { napi_throw_error(env, NULL, "cannot append file observation"); return 0; }
+  return 1;
+}
+
+static int observe_directory(napi_env env, int dir_fd, const char *prefix,
+                             napi_value members, uint32_t *count) {
+  int scan_fd = dup(dir_fd);
+  if (scan_fd < 0) { napi_throw_error(env, NULL, "filesystem observation directory duplication failed"); return 0; }
+  DIR *directory = fdopendir(scan_fd);
+  if (directory == NULL) { close(scan_fd); napi_throw_error(env, NULL, "filesystem observation directory open failed"); return 0; }
+  struct dirent *entry;
+  while ((entry = readdir(directory)) != NULL) {
+    if (strcmp(entry->d_name, ".") == 0 || strcmp(entry->d_name, "..") == 0) continue;
+    char relative[PATH_MAX];
+    int written = snprintf(relative, sizeof(relative), "%s%s%s", prefix,
+                           prefix[0] == '\0' ? "" : "/", entry->d_name);
+    if (written < 1 || (size_t)written >= sizeof(relative)) {
+      closedir(directory); napi_throw_error(env, NULL, "filesystem observation path is too long"); return 0;
+    }
+    struct stat named_stat;
+    if (fstatat(dir_fd, entry->d_name, &named_stat, AT_SYMLINK_NOFOLLOW) != 0 ||
+        (!S_ISDIR(named_stat.st_mode) && !S_ISREG(named_stat.st_mode))) {
+      closedir(directory); napi_throw_error(env, NULL, "filesystem observation encountered a symlink, special file, or changed member"); return 0;
+    }
+    int child_fd = openat(dir_fd, entry->d_name, O_RDONLY | O_NOFOLLOW | O_CLOEXEC);
+    if (child_fd < 0) { closedir(directory); napi_throw_error(env, NULL, "filesystem observation member changed or cannot be opened"); return 0; }
+    struct stat before;
+    if (fstat(child_fd, &before) != 0) { close(child_fd); closedir(directory); napi_throw_error(env, NULL, "filesystem observation member cannot be stat'd"); return 0; }
+    if (S_ISDIR(before.st_mode)) {
+      if (!append_directory_member(env, members, count, relative, &before) ||
+          !observe_directory(env, child_fd, relative, members, count)) {
+        close(child_fd); closedir(directory); return 0;
+      }
+      close(child_fd);
+      continue;
+    }
+    if (!S_ISREG(before.st_mode) || before.st_nlink != 1 || before.st_size < 0) {
+      close(child_fd); closedir(directory); napi_throw_error(env, NULL, "filesystem observation encountered an unsupported member"); return 0;
+    }
+    size_t length = 0, capacity = before.st_size > 0 ? (size_t)before.st_size : 1;
+    unsigned char *bytes = malloc(capacity);
+    if (bytes == NULL) { close(child_fd); closedir(directory); napi_throw_error(env, NULL, "filesystem observation allocation failed"); return 0; }
+    for (;;) {
+      if (length == capacity) {
+        if (capacity > SIZE_MAX / 2) { free(bytes); close(child_fd); closedir(directory); napi_throw_error(env, NULL, "filesystem observation file is too large"); return 0; }
+        size_t next = capacity * 2; unsigned char *grown = realloc(bytes, next);
+        if (grown == NULL) { free(bytes); close(child_fd); closedir(directory); napi_throw_error(env, NULL, "filesystem observation allocation failed"); return 0; }
+        bytes = grown; capacity = next;
+      }
+      ssize_t read_count = read(child_fd, bytes + length, capacity - length);
+      if (read_count < 0) { free(bytes); close(child_fd); closedir(directory); napi_throw_error(env, NULL, "filesystem observation read failed"); return 0; }
+      if (read_count == 0) break;
+      length += (size_t)read_count;
+    }
+    struct stat after;
+    if (fstat(child_fd, &after) != 0 || !same_member_stat(&before, &after) || (size_t)after.st_size != length) {
+      free(bytes); close(child_fd); closedir(directory); napi_throw_error(env, NULL, "filesystem observation member changed while being read"); return 0;
+    }
+    int ok = append_file_member(env, members, count, relative, &after, bytes, length);
+    free(bytes); close(child_fd);
+    if (!ok) { closedir(directory); return 0; }
+  }
+  if (closedir(directory) != 0) { napi_throw_error(env, NULL, "filesystem observation directory close failed"); return 0; }
+  return 1;
+}
+
+static napi_value ObserveFilesystemTreeNative(napi_env env, napi_callback_info info) {
+  size_t argc = 1; napi_value argv[1], result, members;
+  char root[PATH_MAX];
+  NAPI_OK(napi_get_cb_info(env, info, &argc, argv, NULL, NULL), "cannot read native arguments");
+  if (argc != 1 || !read_string(env, argv[0], root, sizeof(root), "root must be a bounded absolute path") || root[0] != '/') return NULL;
+  int root_fd = open(root, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
+  if (root_fd < 0) return throw_last(env, "filesystem observation root cannot be opened");
+  struct stat root_stat;
+  if (fstat(root_fd, &root_stat) != 0 || !S_ISDIR(root_stat.st_mode)) { close(root_fd); return throw_last(env, "filesystem observation root is not a directory"); }
+  NAPI_OK(napi_create_object(env, &result), "cannot create filesystem observation");
+  NAPI_OK(napi_create_array(env, &members), "cannot create filesystem observation members");
+  uint32_t count = 0;
+  if (!observe_directory(env, root_fd, "", members, &count)) { close(root_fd); return NULL; }
+  close(root_fd);
+  NAPI_OK(napi_set_named_property(env, result, "members", members), "cannot set filesystem observation members");
+  if (!set_int64(env, result, "rootMode", (int64_t)root_stat.st_mode)) return NULL;
+  char decimal[64];
+  snprintf(decimal, sizeof(decimal), "%llu", (unsigned long long)root_stat.st_dev);
+  if (!set_member_string(env, result, "rootDevice", decimal)) return NULL;
+  snprintf(decimal, sizeof(decimal), "%llu", (unsigned long long)root_stat.st_ino);
+  if (!set_member_string(env, result, "rootInode", decimal)) return NULL;
+  return result;
+}
+
 static napi_value Init(napi_env env, napi_value exports) {
   napi_value value;
   NAPI_OK(napi_create_function(env, "readFileBoundNative", NAPI_AUTO_LENGTH, ReadFileBoundNative, NULL, &value), "cannot export bound read");
   NAPI_OK(napi_set_named_property(env, exports, "readFileBoundNative", value), "cannot export bound read");
+  NAPI_OK(napi_create_function(env, "observeFilesystemTreeNative", NAPI_AUTO_LENGTH, ObserveFilesystemTreeNative, NULL, &value), "cannot export filesystem observation");
+  NAPI_OK(napi_set_named_property(env, exports, "observeFilesystemTreeNative", value), "cannot export filesystem observation");
   NAPI_OK(napi_create_function(env, "openParentDirectory", NAPI_AUTO_LENGTH, OpenParentDirectory, NULL, &value), "cannot export openParentDirectory");
   NAPI_OK(napi_set_named_property(env, exports, "openParentDirectory", value), "cannot export openParentDirectory");
   NAPI_OK(napi_create_function(env, "closeParentDirectory", NAPI_AUTO_LENGTH, CloseParentDirectory, NULL, &value), "cannot export closeParentDirectory");

package/src/native/loader.mjs

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 const PACKAGE_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const MANIFEST_PATH = path.join(PACKAGE_ROOT, "prebuild-manifest.json");
 const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
-const EXPECTED_EXPORTS = Object.freeze(["closeParentDirectory", "openParentDirectory", "platform", "readFileBoundNative", "renameDirectoryNoReplace"]);
+const EXPECTED_EXPORTS = Object.freeze(["closeParentDirectory", "observeFilesystemTreeNative", "openParentDirectory", "platform", "readFileBoundNative", "renameDirectoryNoReplace"]);
 const PLATFORM_KEYS = Object.freeze(["darwin-arm64", "darwin-x64", "linux-arm64-gnu", "linux-x64-gnu"]);
 
 function fail(message) {

package/src/native/prebuild-manifest.json

@@ -10,10 +10,11 @@
       "libc": "none",
       "binary": "prebuilds/darwin-arm64/bound_read.darwin-arm64.node",
       "mode": 420,
-      "sha256": "edf0be6988f0c0d26ec03860e55d81be8ddf85fd82d29aba4ab6963bd58f9651",
+      "sha256": "19ce71026b737ba6b56da78ffabca4bb25f21249c30b545d68633d4b77547fde",
       "napi": 10,
       "exports": [
         "closeParentDirectory",
+        "observeFilesystemTreeNative",
         "openParentDirectory",
         "platform",
         "readFileBoundNative",
@@ -27,10 +28,11 @@
       "libc": "none",
       "binary": "prebuilds/darwin-x64/bound_read.darwin-x64.node",
       "mode": 420,
-      "sha256": "cf11633c8ea804a4c9af58eb205852d38eb6f49979bdad21abc93ba49184ac41",
+      "sha256": "e01e4a1df3554da857189f483174d0480eb36063ce17b5857a23fa8a02f4a664",
       "napi": 10,
       "exports": [
         "closeParentDirectory",
+        "observeFilesystemTreeNative",
         "openParentDirectory",
         "platform",
         "readFileBoundNative",
@@ -44,10 +46,11 @@
       "libc": "glibc",
       "binary": "prebuilds/linux-arm64-gnu/bound_read.linux-arm64-gnu.node",
       "mode": 420,
-      "sha256": "577db2c4b200ecddf0e5807034a57afa0f4d98fd6ee7cdbaeb358f3ff05313ae",
+      "sha256": "7b7fd1188d2bbf356fe8c44690fd80bc7fb02e9f6f9dc7ee1c10834bf1c519b1",
       "napi": 10,
       "exports": [
         "closeParentDirectory",
+        "observeFilesystemTreeNative",
         "openParentDirectory",
         "platform",
         "readFileBoundNative",
@@ -61,10 +64,11 @@
       "libc": "glibc",
       "binary": "prebuilds/linux-x64-gnu/bound_read.linux-x64-gnu.node",
       "mode": 420,
-      "sha256": "f12ed96d4b5a338d87232a074b5d95117d81c5fdeb31f79c664a93c17f28a809",
+      "sha256": "749b69ba1b7da3496e59f92f2ca8d04800031b2479c13b3ca63555ee69671acc",
       "napi": 10,
       "exports": [
         "closeParentDirectory",
+        "observeFilesystemTreeNative",
         "openParentDirectory",
         "platform",
         "readFileBoundNative",

package/src/native/prebuild-release-receipt.json

@@ -8,33 +8,33 @@
   },
   "source": {
     "path": "packages/skill-family-harness-node/src/native/bound_read.c",
-    "sha256": "58928393adc6921a399685446784efc7eead3987b99378ffd7ac23287d4ccf74"
+    "sha256": "10cfc3ff44343a532629879841f9ae7a12b78d818d596f85af3915cea9832c15"
   },
   "buildRecipe": {
     "path": "packages/skill-family-harness-node/src/native/binding.gyp",
     "sha256": "1631420afe903b1978a856dbeadd37a655a704cd7ded9d1ab6696f87e1116d7f"
   },
-  "manifestSha256": "1ded122cb8692d7ec6038bf79b11baaa330d94e3407cff159b9d94f61ee8337e",
+  "manifestSha256": "76a1e6f99ef5980043df4f328bbe9623dfc8cbba6655e008a8bb1d53d9e49ace",
   "inputs": [
     {
       "platformKey": "darwin-arm64",
-      "platformReceiptSha256": "43a7f1ba15b9811f115bcd4868a8e63e79472731c8027d7744a6db04e69fb2e2",
-      "binarySha256": "edf0be6988f0c0d26ec03860e55d81be8ddf85fd82d29aba4ab6963bd58f9651"
+      "platformReceiptSha256": "eff6c0350d7cb7f949346593af1b65f5791b5545e67eba192ef66bd7af7db93d",
+      "binarySha256": "19ce71026b737ba6b56da78ffabca4bb25f21249c30b545d68633d4b77547fde"
     },
     {
       "platformKey": "darwin-x64",
-      "platformReceiptSha256": "4f1db41cd657ddfdf3a10926f7372674b36072bb395ee7b3f2f2851b5b7c0b8d",
-      "binarySha256": "cf11633c8ea804a4c9af58eb205852d38eb6f49979bdad21abc93ba49184ac41"
+      "platformReceiptSha256": "55254e51f14fbe7fa5e6d5a64bf23db3926a49758fbe6afb20bc4c8dbc8b30bb",
+      "binarySha256": "e01e4a1df3554da857189f483174d0480eb36063ce17b5857a23fa8a02f4a664"
     },
     {
       "platformKey": "linux-arm64-gnu",
-      "platformReceiptSha256": "f024e7f765ffcd8162fc2d7accc60806a337ff7945315dbbaf2609bdea87001a",
-      "binarySha256": "577db2c4b200ecddf0e5807034a57afa0f4d98fd6ee7cdbaeb358f3ff05313ae"
+      "platformReceiptSha256": "3e4df89d8b211d0700f436314ec6302999e086602bf26d68797d285d40ab7941",
+      "binarySha256": "7b7fd1188d2bbf356fe8c44690fd80bc7fb02e9f6f9dc7ee1c10834bf1c519b1"
     },
     {
       "platformKey": "linux-x64-gnu",
-      "platformReceiptSha256": "aca0b64b4943dfdae39a2870d75a745088694a84f27b7ceafbfded4234a5fb73",
-      "binarySha256": "f12ed96d4b5a338d87232a074b5d95117d81c5fdeb31f79c664a93c17f28a809"
+      "platformReceiptSha256": "672d066df845073da0999f69659e772dec3cf0d6b3e34bf74907a5e7fd5190c9",
+      "binarySha256": "749b69ba1b7da3496e59f92f2ca8d04800031b2479c13b3ca63555ee69671acc"
     }
   ]
 }

package/src/native/prebuild-sbom.json

@@ -4,7 +4,7 @@
   "status": "stable",
   "source": {
     "path": "packages/skill-family-harness-node/src/native/bound_read.c",
-    "sha256": "58928393adc6921a399685446784efc7eead3987b99378ffd7ac23287d4ccf74"
+    "sha256": "10cfc3ff44343a532629879841f9ae7a12b78d818d596f85af3915cea9832c15"
   },
   "buildRecipe": {
     "path": "packages/skill-family-harness-node/src/native/binding.gyp",
@@ -14,25 +14,25 @@
     {
       "platformKey": "darwin-arm64",
       "binary": "prebuilds/darwin-arm64/bound_read.darwin-arm64.node",
-      "sha256": "edf0be6988f0c0d26ec03860e55d81be8ddf85fd82d29aba4ab6963bd58f9651",
+      "sha256": "19ce71026b737ba6b56da78ffabca4bb25f21249c30b545d68633d4b77547fde",
       "license": "Apache-2.0"
     },
     {
       "platformKey": "darwin-x64",
       "binary": "prebuilds/darwin-x64/bound_read.darwin-x64.node",
-      "sha256": "cf11633c8ea804a4c9af58eb205852d38eb6f49979bdad21abc93ba49184ac41",
+      "sha256": "e01e4a1df3554da857189f483174d0480eb36063ce17b5857a23fa8a02f4a664",
       "license": "Apache-2.0"
     },
     {
       "platformKey": "linux-arm64-gnu",
       "binary": "prebuilds/linux-arm64-gnu/bound_read.linux-arm64-gnu.node",
-      "sha256": "577db2c4b200ecddf0e5807034a57afa0f4d98fd6ee7cdbaeb358f3ff05313ae",
+      "sha256": "7b7fd1188d2bbf356fe8c44690fd80bc7fb02e9f6f9dc7ee1c10834bf1c519b1",
       "license": "Apache-2.0"
     },
     {
       "platformKey": "linux-x64-gnu",
       "binary": "prebuilds/linux-x64-gnu/bound_read.linux-x64-gnu.node",
-      "sha256": "f12ed96d4b5a338d87232a074b5d95117d81c5fdeb31f79c664a93c17f28a809",
+      "sha256": "749b69ba1b7da3496e59f92f2ca8d04800031b2479c13b3ca63555ee69671acc",
       "license": "Apache-2.0"
     }
   ]

package/src/supervise-process.mjs

@@ -61,6 +61,7 @@ export const WATCHDOG_REASONS = Object.freeze([
   "no_terminal_result",
   "residual_process_group",
   "context_budget_exhausted",
+  "output_limit_exceeded",
 ]);
 
 /** Termination reason: the deterministic mapping consumers consume (8 values). */
@@ -73,6 +74,7 @@ export const TERMINATION_REASONS = Object.freeze([
   "completed",
   "child_exit",
   "context_budget_exhausted",
+  "output_limit_exceeded",
 ]);
 
 /** Process status of the supervised process (7 values). */
@@ -115,6 +117,25 @@ const TIMEOUT_WATCHDOG_REASONS = new Set([
   "tool_lease_expired",
 ]);
 
+const OUTPUT_LIMIT_FIELDS = Object.freeze(["stdout", "stderr"]);
+const MAX_SAFE_OUTPUT_BYTES = Number.MAX_SAFE_INTEGER;
+
+function validateOutputByteLimits(limits) {
+  if (limits === undefined) return null;
+  if (!isPlainObject(limits)) return "outputByteLimits must be a plain object";
+  const fields = Object.keys(limits);
+  if (fields.length === 0 || fields.some((field) => !OUTPUT_LIMIT_FIELDS.includes(field))) {
+    return "outputByteLimits must contain stdout and/or stderr only";
+  }
+  for (const field of fields) {
+    const value = limits[field];
+    if (!Number.isInteger(value) || value < 0 || value > MAX_SAFE_OUTPUT_BYTES) {
+      return `outputByteLimits.${field} must be an integer from 0 to Number.MAX_SAFE_INTEGER`;
+    }
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Option and policy validation
 // ---------------------------------------------------------------------------
@@ -164,7 +185,7 @@ function validateOptions(options) {
   const {
     command, args, cwd, env,
     timeoutPolicy, progressPaths, terminalProgressPaths, terminalGraceSeconds,
-    checkIntervalSeconds, longToolActive, budgetExhausted, evidencePath, rawSink, rawStreamSink,
+    checkIntervalSeconds, longToolActive, budgetExhausted, evidencePath, rawSink, rawStreamSink, outputByteLimits,
   } = options;
   if (typeof command !== "string" || command.length === 0) {
     throw new TypeError("superviseProcess: command must be a non-empty string");
@@ -220,6 +241,8 @@ function validateOptions(options) {
     const problem = validateRawSink(rawSink);
     if (problem) throw new TypeError(`superviseProcess: ${problem}`);
   }
+  const outputLimitProblem = validateOutputByteLimits(outputByteLimits);
+  if (outputLimitProblem) throw new TypeError(`superviseProcess: ${outputLimitProblem}`);
   const policyProblem = validateTimeoutPolicy(timeoutPolicy);
   if (policyProblem) {
     throw mechanismError("timeout-policy-invalid", policyProblem);
@@ -308,8 +331,8 @@ async function openRawSinkFile(captured, filename) {
   return handle;
 }
 
-function makeRawStreamState(handle) {
-  return { handle, hash: createHash("sha256"), bytes: 0, queue: Promise.resolve(), closed: false };
+function makeRawStreamState(handle, limit) {
+  return { handle, hash: createHash("sha256"), bytes: 0, limit, queue: Promise.resolve(), closed: false };
 }
 
 function enqueueRawChunk(state, chunk) {
@@ -503,6 +526,7 @@ const WATCHDOG_TO_TERMINATION = Object.freeze({
   no_terminal_result: "completed",
   residual_process_group: "child_exit",
   context_budget_exhausted: "context_budget_exhausted",
+  output_limit_exceeded: "output_limit_exceeded",
 });
 
 function mapWatchdogToTermination(watchdogReason) {
@@ -547,6 +571,8 @@ function buildEnvelope({
   signalSequence,
   forcedKill,
   timeoutPolicy,
+  outputByteLimits,
+  outputLimitExceeded,
   progressPaths,
   terminalProgressPaths,
   terminalSeen,
@@ -564,9 +590,9 @@ function buildEnvelope({
     sawLeaderExit,
   );
   const ok = watchdogReason === "terminal_progress"
-    ? true
+    ? outputLimitExceeded === null
     : watchdogReason === null
-      ? exitStatus === 0
+      ? exitStatus === 0 && outputLimitExceeded === null
       : false;
   const evidence = {
     command,
@@ -587,6 +613,7 @@ function buildEnvelope({
     startupProgressPaths: progressPaths,
     terminalProgressPaths,
     timeoutPolicy,
+    ...(outputByteLimits !== undefined ? { outputByteLimits, outputLimitExceeded } : {}),
     ...(terminalSeen ? { terminalIdentity: terminalSeen.identity } : {}),
     ...(terminalSeen?.status !== undefined ? { terminalStatus: terminalSeen.status } : {}),
     ...(residualGroupCleanupCompleted !== undefined
@@ -634,6 +661,9 @@ function buildEnvelope({
  *   terminal record must persist before the mechanism closes the process
  *   with watchdog_reason terminal_progress.
  * @param {number} [options.checkIntervalSeconds=1] - supervision cadence.
+ * @param {{stdout?: number, stderr?: number}} [options.outputByteLimits] -
+ *   optional independent raw-byte caps; equal is allowed, first excess
+ *   immediately enters the existing process-group termination path.
  * @param {() => boolean} [options.longToolActive] - consumer-owned long-tool
  *   activity probe; enables the tool-lease dimension (requires
  *   toolLeaseSeconds). Stream-idle is suspended while the probe is true.
@@ -679,6 +709,7 @@ export async function superviseProcess(options, deps = {}) {
     evidencePath,
   } = options;
   const sink = options.rawSink ?? null;
+  const outputByteLimits = options.outputByteLimits;
   let rawStreams = null;
   if (sink !== null) {
     try {
@@ -692,8 +723,8 @@ export async function superviseProcess(options, deps = {}) {
         throw error;
       }
       rawStreams = {
-        stdout: makeRawStreamState(stdoutHandle),
-        stderr: makeRawStreamState(stderrHandle),
+        stdout: makeRawStreamState(stdoutHandle, outputByteLimits?.stdout),
+        stderr: makeRawStreamState(stderrHandle, outputByteLimits?.stderr),
       };
     } catch (error) {
       if (rawStreams?.stdout) await closeRawStreamState(rawStreams.stdout).catch(() => {});
@@ -759,6 +790,8 @@ export async function superviseProcess(options, deps = {}) {
     residualGroupCleanupCompleted: undefined,
     watchdogSignalSucceeded: false,
     finalizing: false,
+    outputLimitExceeded: null,
+    outputBytes: { stdout: 0, stderr: 0 },
   };
   const signalSequence = [];
   let interval = null;
@@ -867,6 +900,9 @@ export async function superviseProcess(options, deps = {}) {
     let watchdogReason = lifecycle.vanish
       ? "no_terminal_result"
       : (termination?.reason ?? null);
+    if (watchdogReason === null && lifecycle.outputLimitExceeded !== null) {
+      watchdogReason = "output_limit_exceeded";
+    }
 
     // Terminal requirement reconciliation (R9-equivalent): when terminal
     // progress paths are configured and the close was authoritative
@@ -916,6 +952,8 @@ export async function superviseProcess(options, deps = {}) {
       signalSequence,
       forcedKill: termination?.forcedKill === true,
       timeoutPolicy,
+      outputByteLimits,
+      outputLimitExceeded: lifecycle.outputLimitExceeded,
       progressPaths,
       terminalProgressPaths,
       terminalSeen,
@@ -1005,6 +1043,8 @@ export async function superviseProcess(options, deps = {}) {
       signalSequence: [],
       forcedKill: false,
       timeoutPolicy,
+      outputByteLimits,
+      outputLimitExceeded: null,
       progressPaths,
       terminalProgressPaths,
       terminalSeen: null,
@@ -1260,6 +1300,24 @@ export async function superviseProcess(options, deps = {}) {
     }
   }
 
+  function handleOutputChunk(stream, chunk) {
+    const bytes = Buffer.from(chunk);
+    lifecycle.outputBytes[stream] += bytes.length;
+    const limit = outputByteLimits?.[stream];
+    let saved = bytes;
+    if (limit !== undefined) {
+      const allowed = Math.max(0, limit - (lifecycle.outputBytes[stream] - bytes.length));
+      saved = bytes.subarray(0, allowed);
+      if (lifecycle.outputBytes[stream] > limit) {
+        lifecycle.outputLimitExceeded ??= stream;
+        if (beginTermination("output_limit_exceeded", d.nowMs())) superviseLifecycle(d.nowMs());
+      }
+    }
+    if (rawStreams && saved.length > 0) {
+      void enqueueRawChunk(rawStreams[stream], saved).catch((error) => { lifecycle.runtimeError = error; });
+    }
+  }
+
   // Wire the child events.
   child.stdout?.on("data", () => {
     lastStreamActivityAtMs = d.nowMs();
@@ -1267,12 +1325,8 @@ export async function superviseProcess(options, deps = {}) {
   child.stderr?.on("data", () => {
     lastStreamActivityAtMs = d.nowMs();
   });
-  child.stdout?.on("data", (chunk) => {
-    if (rawStreams) void enqueueRawChunk(rawStreams.stdout, chunk).catch((error) => { lifecycle.runtimeError = error; });
-  });
-  child.stderr?.on("data", (chunk) => {
-    if (rawStreams) void enqueueRawChunk(rawStreams.stderr, chunk).catch((error) => { lifecycle.runtimeError = error; });
-  });
+  child.stdout?.on("data", (chunk) => handleOutputChunk("stdout", chunk));
+  child.stderr?.on("data", (chunk) => handleOutputChunk("stderr", chunk));
   child.on("exit", (code, signalCode) => {
     lifecycle.leaderResult = { code, signalCode };
     superviseLifecycle(d.nowMs());