@dommaker/harness 1.2.2 → 1.3.0

package/src/completion-checkers/tdd-chain.ts

@@ -3,7 +3,7 @@
  *
  * 协议（写死为机制本体，不进配置）：
  * - 实现 commit 必须带 trailer `Tested-By: <sha>`
- * - 被引 sha 须 a) 在本 WU 提交集内 b) 序列位置在本 commit 之前（比位置不比时间戳）c) 其文件清单命中 test_globs
+ * - 被引 sha 须 a) 在本提交集内 b) 序列位置在本 commit 之前（比位置不比时间戳）c) 其文件清单命中 test_globs
  * - 豁免：trailer `Tests: none` → waiver（放行记台账）；纯非代码/纯测试 commit 天然免检
  */
 
@@ -44,7 +44,7 @@ export function verifyTddChain(
     const ref = m[1].toLowerCase();
     const j = commits.findIndex((c) => c.sha.toLowerCase().startsWith(ref));
     if (j === -1) {
-      return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 不在本 WU 提交集内` };
+      return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 不在本提交集内` };
     }
     if (j >= i) {
       return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 位置不在本 commit 之前` };

package/src/completion-checkers/types.ts

@@ -1,12 +1,12 @@
 /**
- * Completion Checkers 类型定义（T7-E1，studio#160）
+ * Completion Checkers 类型定义
  *
  * 三个纯判定函数共享的输入/输出/配置类型。
  * 与 ConstraintCheck 闭环注册表无关：直接 export，不注册、不碰 checkers/index.ts。
- * 函数不碰文件系统与 git，commits 由调用方（studio 侧 git log）供给。
+ * 函数不碰文件系统与 git，commits 由调用方（git log）供给。
  */
 
-/** WU 提交输入（有序，base..HEAD 升序） */
+/** 提交集内的单个提交输入（有序，base..HEAD 升序） */
 export interface CommitInput {
   /** 完整 sha */
   sha: string;
@@ -49,7 +49,7 @@ export interface PhaseFormatResult {
 
 /** verifyContractPresence 上下文（类型→字段的判定方法映射是代码不是配置） */
 export interface ContractPresenceContext {
-  /** review 类型契约：studio agent-loop 已解析的 metadata.reviewReport */
+  /** review 类型契约：调用方已解析的 metadata.reviewReport */
   reviewReport?: unknown;
   [key: string]: unknown;
 }
@@ -62,7 +62,7 @@ export interface ContractPresenceResult {
 }
 
 /**
- * completion_checkers 配置（对应 yml 顶层键 `completion_checkers:`，studio 侧自解）。
+ * completion_checkers 配置（对应 yml 顶层键 `completion_checkers:`，消费方自解）。
  * 只配开关/glob/契约类型清单；协议格式（Tested-By、Tests: none、phase 结构）写死为机制本体。
  * 缺省 = 全开 + 默认 glob。
  */

package/src/failure/recorder.ts

@@ -25,7 +25,7 @@ export interface FailureRecorderConfig {
  *
  * 用法：
  * ```typescript
- * const recorder = new FailureRecorder({ logFile: '.harness/logs/failures.log' });
+ * const recorder = new FailureRecorder({ logFile: DEFAULT_FAILURE_LOG_FILE });
  * await recorder.record({
  *   type: ErrorType.TEST_FAILED,
  *   level: FailureLevel.L1,

package/src/index.ts

@@ -235,6 +235,7 @@ export type { ContextAverages } from './monitoring';
 export {
   ErrorType,
   FailureLevel,
+  DEFAULT_FAILURE_LOG_FILE,
   DEFAULT_CLASSIFICATION_RULES,
   DEFAULT_LEVEL_MAPPING,
   ErrorClassifier,
@@ -339,8 +340,8 @@ export type {
 } from './knowledge';
 
 // ========================================
-// Completion Checkers（T7-E1，studio#160）
-// WU 收尾软观测三纯判定函数：tdd-chain / phase-format / contract-presence。
+// Completion Checkers
+// 提交集收尾软观测三纯判定函数：tdd-chain / phase-format / contract-presence。
 // 纯函数直接 export，不进 ConstraintCheck 闭环注册表。
 // ========================================
 export {
@@ -374,6 +375,14 @@ export type {
 // ========================================
 export { getRegistryPath, getToolsDir } from './tools';
 
+// ========================================
+// 发布物完整性自检（#75 N4 收编：harness 自己最知道自己发了什么）
+// 清单 = 包声明面（package.json main/exports/bin）推导 + 运行时 extras 随源码维护；
+// studio publishPackage 的 dist 校验改调本能力，不再硬编码 harness dist 内部清单。
+// ========================================
+export { getCriticalArtifacts, verifyReleaseArtifacts } from './release';
+export type { ArtifactIntegrityResult } from './release';
+
 // ========================================
 // Hooks 管线
 // ========================================

package/src/knowledge/__tests__/index-generator.test.ts

@@ -103,7 +103,7 @@ Extra text
     it('handles files without frontmatter via best-effort', () => {
       fs.writeFileSync(
         path.join(tmpDir, 'agent-network-core-concepts.md'),
-        '# Agent Network 核心概念\n\n## WorkUnit\nBody\n'
+        '# 核心概念总览\n\n## 设计要点\nBody\n'
       );
 
       const gen = new KnowledgeIndexGenerator(tmpDir);
@@ -115,7 +115,7 @@ Extra text
       // agent-network-* prefix maps to architecture
       expect(fields[2]).toBe('architecture');
       // H2 terms should still be extracted
-      expect(fields[6]).toContain('WorkUnit');
+      expect(fields[6]).toContain('设计要点');
     });
 
     it('excludes .archive directory', () => {

package/src/knowledge/index-generator.ts

@@ -59,7 +59,7 @@ export class KnowledgeIndexGenerator {
       `# Types: ${Object.entries(byType).map(([t, n]) => `${t}:${n}`).join(' ')}`,
       `#`,
       `# Usage:`,
-      `#   grep "<keyword>" ~/.studio/knowledge/_index.md`,
+      `#   grep "<keyword>" ~/.harness/knowledge/_index.md`,
       `#   Then Read the matching file for full content.`,
       `#`,
       `# filename|id|type|title|maturity|tags|terms`,

package/src/release/CONTEXT.md

@@ -0,0 +1,23 @@
+# release/
+
+## 职责
+发布物完整性自检：harness 自己声明并校验自己发布了什么。关键发布物清单的单一来源，替代外部（studio publishPackage）与本仓 release 命令各自的 dist 文件硬编码（harness#77，#75 N4 收编）。
+
+## 核心导出
+- `deriveCriticalArtifacts(manifest)`（`integrity.ts`）——从包声明面（package.json `main`/`exports`/`bin`）推导脚本入口清单（.js/.cjs/.mjs/.d.ts，去 `./` 前缀、剔除非脚本叶子、去重排序）；纯函数
+- `EXTRA_CRITICAL_ARTIFACTS`——声明面推导之外的运行时关键发布物（bin/harness.js 引导期 require 的命令/门禁定义表、`dist/tools/definitions` 数据目录）；与其描述的文件同仓同评审，删改须同步
+- `resolvePackageRoot(fromDir?)`——从模块位置向上按包名解析本包根（源码仓与 node_modules 安装态均可达）
+- `getCriticalArtifacts(pkgRoot?)` / `verifyReleaseArtifacts(pkgRoot?)`——公开 API；pkgRoot 缺省自动解析，外部消费者零参数即自检已安装的 harness
+
+## 依赖关系
+- 无内部依赖（只依赖 node fs/path）
+
+## 约定
+- 清单维护模型：声明面推导为主（目录重构动到 package.json 时清单自动跟随）+ extras 随源码维护；**不新增第三处硬编码清单**
+- 覆盖口径（有意裁决，#77）：深度内部文件（tsc 产出的 dist/knowledge/*、core/constraints/checker.js 等）**不在清单**——非公开契约，存在性由 tsc 构建成功保证；历史上外部硬编码它们正是重构误判（studio 6cf3c329）的根因。旧 studio 清单 checker.js/doctor.js、旧 release 清单 13 项均被本清单取代，覆盖收窄是裁决而非遗漏
+- `__tests__/integrity.test.ts` 的「真实包根清单同步闸门」是重构同步闸门：动 exports/main/bin 或 extras 时该测试强制同步
+- bin 新增引导期 require 的 dist 文件 → extras 加一条 + 测试同步
+
+## 注意事项
+- 挂载点：`harness release` 命令第 4 步（tsc 后校验 dist）；studio publishPackage dist 校验改调本能力（studio#425 配套切换）
+- 公开面只收 `getCriticalArtifacts` / `verifyReleaseArtifacts` + `ArtifactIntegrityResult`（ADR-0003）；derive/resolve 属内部 seam

package/src/release/__tests__/integrity.test.ts

@@ -0,0 +1,157 @@
+/**
+ * 发布物完整性自检测试（harness#77，#75 N4 收编）
+ *
+ * 覆盖：声明面推导（main/exports/bin）、extras 清单守卫、包根向上解析、
+ * 存在性校验、真实包根清单同步闸门。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  HARNESS_PACKAGE_NAME,
+  EXTRA_CRITICAL_ARTIFACTS,
+  deriveCriticalArtifacts,
+  resolvePackageRoot,
+  getCriticalArtifacts,
+  verifyReleaseArtifacts,
+} from '../integrity';
+import type { PackagePublishManifest } from '../integrity';
+
+/** 建临时 fixture 包根：写 package.json + 按清单造文件/目录 */
+function makeFixture(manifest: PackagePublishManifest, artifacts: string[]): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-release-integrity-'));
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify(manifest));
+  for (const artifact of artifacts) {
+    const abs = path.join(root, artifact);
+    if (/\.[cm]?js$|\.d\.ts$/.test(artifact)) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, '');
+    } else {
+      fs.mkdirSync(abs, { recursive: true });
+    }
+  }
+  return root;
+}
+
+describe('deriveCriticalArtifacts', () => {
+  it('收集 main/exports/bin 声明的脚本入口，去 ./ 前缀、去重、排序，非脚本叶子剔除', () => {
+    const manifest: PackagePublishManifest = {
+      name: HARNESS_PACKAGE_NAME,
+      main: './dist/index.js',
+      bin: { harness: './bin/harness.js' },
+      exports: {
+        '.': {
+          types: './dist/index.d.ts',
+          require: './dist/index.js',
+          import: './dist/index.js',
+        },
+        './core': './dist/core/index.js',
+        './package.json': './package.json',
+      },
+    };
+    expect(deriveCriticalArtifacts(manifest)).toEqual([
+      'bin/harness.js',
+      'dist/core/index.js',
+      'dist/index.d.ts',
+      'dist/index.js',
+    ]);
+  });
+
+  it('exports 为字符串、bin 为字符串、null 条目（兜底禁用）安全', () => {
+    const manifest: PackagePublishManifest = {
+      name: HARNESS_PACKAGE_NAME,
+      main: 'dist/index.js',
+      bin: 'bin/harness.js',
+      exports: { '.': './dist/index.js', './forbidden': null },
+    };
+    expect(deriveCriticalArtifacts(manifest)).toEqual(['bin/harness.js', 'dist/index.js']);
+  });
+
+  it('无声明字段返回空清单', () => {
+    expect(deriveCriticalArtifacts({ name: HARNESS_PACKAGE_NAME })).toEqual([]);
+  });
+});
+
+describe('EXTRA_CRITICAL_ARTIFACTS', () => {
+  it('覆盖 bin 引导定义表与 tools 运行时数据目录（随源码维护，删改须同评审）', () => {
+    expect(EXTRA_CRITICAL_ARTIFACTS).toEqual([
+      'dist/cli/commands/definitions.js',
+      'dist/gates/definitions.js',
+      'dist/tools/definitions',
+    ]);
+  });
+});
+
+describe('resolvePackageRoot', () => {
+  it('从源码位置向上解析到本仓包根', () => {
+    const root = resolvePackageRoot(__dirname);
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+    expect(pkg.name).toBe(HARNESS_PACKAGE_NAME);
+  });
+
+  it('无匹配包根时抛错并提示显式传入 pkgRoot', () => {
+    const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-no-pkg-root-'));
+    const nested = path.join(bare, 'deep', 'nested');
+    fs.mkdirSync(nested, { recursive: true });
+    expect(() => resolvePackageRoot(nested)).toThrow(/pkgRoot/);
+  });
+});
+
+describe('getCriticalArtifacts / verifyReleaseArtifacts（fixture 包根）', () => {
+  const FIXTURE_MANIFEST: PackagePublishManifest = {
+    name: HARNESS_PACKAGE_NAME,
+    main: './dist/index.js',
+    bin: './bin/harness.js',
+    exports: { '.': './dist/index.js' },
+  };
+  const FIXTURE_ARTIFACTS = [
+    'dist/index.js',
+    'bin/harness.js',
+    ...EXTRA_CRITICAL_ARTIFACTS,
+  ];
+
+  it('清单 = 声明面推导 + extras', () => {
+    const root = makeFixture(FIXTURE_MANIFEST, FIXTURE_ARTIFACTS);
+    expect(getCriticalArtifacts(root)).toEqual([
+      'bin/harness.js',
+      'dist/cli/commands/definitions.js',
+      'dist/gates/definitions.js',
+      'dist/index.js',
+      'dist/tools/definitions',
+    ]);
+  });
+
+  it('全部就位 → ok:true', () => {
+    const root = makeFixture(FIXTURE_MANIFEST, FIXTURE_ARTIFACTS);
+    const result = verifyReleaseArtifacts(root);
+    expect(result).toMatchObject({ ok: true, pkgRoot: root, missing: [] });
+  });
+
+  it('缺文件 → ok:false 且 missing 指名', () => {
+    const root = makeFixture(FIXTURE_MANIFEST, FIXTURE_ARTIFACTS);
+    fs.rmSync(path.join(root, 'dist', 'tools', 'definitions'), { recursive: true, force: true });
+    const result = verifyReleaseArtifacts(root);
+    expect(result.ok).toBe(false);
+    expect(result.missing).toEqual(['dist/tools/definitions']);
+  });
+});
+
+describe('真实包根清单同步闸门', () => {
+  it('真实 package.json 推导覆盖全部声明入口 + extras（重构动声明面时本测试强制同步）', () => {
+    const root = resolvePackageRoot(__dirname);
+    const artifacts = getCriticalArtifacts(root);
+    for (const required of [
+      'dist/index.js',
+      'dist/core/index.js',
+      'dist/presets/index.js',
+      'dist/context/index.js',
+      'dist/gates/index.js',
+      'bin/harness.js',
+      ...EXTRA_CRITICAL_ARTIFACTS,
+    ]) {
+      expect(artifacts).toContain(required);
+    }
+  });
+});

package/src/release/index.ts

@@ -0,0 +1,13 @@
+export {
+  HARNESS_PACKAGE_NAME,
+  EXTRA_CRITICAL_ARTIFACTS,
+  deriveCriticalArtifacts,
+  resolvePackageRoot,
+  getCriticalArtifacts,
+  verifyReleaseArtifacts,
+} from './integrity';
+export type {
+  PackagePublishManifest,
+  PackageExports,
+  ArtifactIntegrityResult,
+} from './integrity';

package/src/release/integrity.ts

@@ -0,0 +1,141 @@
+/**
+ * 发布物完整性自检（harness#77，#75 N4 收编）
+ *
+ * harness 自己最知道自己发了什么：关键发布物清单不再由外部（studio publishPackage）
+ * 或本仓 release 命令各自硬编码 dist 内部文件，而是从包声明面（package.json
+ * main/exports/bin）运行时推导 + 少量运行时 extras 随源码维护——目录重构动到
+ * 声明面时清单自动跟随，extras 与其描述的文件同仓同评审。
+ *
+ * 公开面（barrel）：getCriticalArtifacts / verifyReleaseArtifacts。
+ * studio publishPackage 的 dist 校验改调本能力，替换硬编码清单（studio#425 配套切换）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/** 本包名（包根向上解析的身份锚点，同 bin 名同源） */
+export const HARNESS_PACKAGE_NAME = '@dommaker/harness';
+
+/** package.json 发布面形状（只关心与发布物定位相关字段） */
+export interface PackagePublishManifest {
+  name?: string;
+  main?: string;
+  bin?: string | Record<string, string>;
+  exports?: PackageExports;
+}
+
+/** exports 字段形状：字符串叶子 / null（兜底禁用）/ 条件对象递归 */
+export type PackageExports = string | null | { [key: string]: PackageExports };
+
+/**
+ * 推导之外、随源码维护的运行时关键发布物。
+ * 声明面推导只覆盖入口文件；以下入口的运行时依赖由本清单兜底。
+ */
+export const EXTRA_CRITICAL_ARTIFACTS: readonly string[] = [
+  // bin/harness.js 引导期 require 的命令/门禁定义表
+  'dist/cli/commands/definitions.js',
+  'dist/gates/definitions.js',
+  // getToolsDir/getRegistryPath 运行时数据目录（build 脚本 cp -r，tsc 不产出）
+  'dist/tools/definitions',
+];
+
+const CRITICAL_SUFFIXES = ['.js', '.cjs', '.mjs', '.d.ts'];
+
+function collectExportsLeaves(exportsField: PackageExports | undefined, out: string[]): void {
+  if (typeof exportsField === 'string') {
+    out.push(exportsField);
+    return;
+  }
+  if (!exportsField || typeof exportsField !== 'object') return;
+  for (const value of Object.values(exportsField)) {
+    collectExportsLeaves(value, out);
+  }
+}
+
+/**
+ * 从包声明面推导关键发布物清单：main + bin + exports 全部脚本入口。
+ * 去 ./ 前缀，剔除非脚本叶子（如 ./package.json 自导出），去重排序。
+ */
+export function deriveCriticalArtifacts(manifest: PackagePublishManifest): string[] {
+  const collected: string[] = [];
+  if (manifest.main) collected.push(manifest.main);
+  if (typeof manifest.bin === 'string') collected.push(manifest.bin);
+  else if (manifest.bin && typeof manifest.bin === 'object') {
+    collected.push(...Object.values(manifest.bin));
+  }
+  collectExportsLeaves(manifest.exports, collected);
+  return [...new Set(
+    collected
+      .map(p => p.replace(/^\.\//, ''))
+      .filter(p => CRITICAL_SUFFIXES.some(suffix => p.endsWith(suffix)))
+  )].sort();
+}
+
+function isHarnessPackageRoot(dir: string): boolean {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+    return pkg?.name === HARNESS_PACKAGE_NAME;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 从 fromDir（缺省本模块编译位置）向上解析本包根。
+ * 源码仓（src/release → 仓根）与发布包（node_modules/@dommaker/harness/dist/release
+ * → 包根）均可达；到文件系统根仍无匹配则抛错。
+ */
+export function resolvePackageRoot(fromDir: string = __dirname): string {
+  let dir = path.resolve(fromDir);
+  for (;;) {
+    if (isHarnessPackageRoot(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `[harness] 无法从 ${fromDir} 向上定位 ${HARNESS_PACKAGE_NAME} 包根；请显式传入 pkgRoot。`
+  );
+}
+
+function resolveRoot(pkgRoot?: string): string {
+  return pkgRoot ? path.resolve(pkgRoot) : resolvePackageRoot();
+}
+
+/**
+ * 关键发布物清单（相对包根路径，排序去重）。
+ * pkgRoot 缺省时自动解析本包根——外部消费者（studio）零参数即自检已安装的 harness。
+ */
+export function getCriticalArtifacts(pkgRoot?: string): string[] {
+  const root = resolveRoot(pkgRoot);
+  const manifest: PackagePublishManifest = JSON.parse(
+    fs.readFileSync(path.join(root, 'package.json'), 'utf-8')
+  );
+  return [...new Set([...deriveCriticalArtifacts(manifest), ...EXTRA_CRITICAL_ARTIFACTS])].sort();
+}
+
+export interface ArtifactIntegrityResult {
+  ok: boolean;
+  pkgRoot: string;
+  /** 清单全量（相对包根路径） */
+  checked: string[];
+  /** 缺失项（相对包根路径） */
+  missing: string[];
+}
+
+/**
+ * 发布物完整性自检：逐项存在性校验（目录/文件均可）。
+ *
+ * 覆盖口径（有意裁决，#77）：清单只锚定声明面及其运行时依赖；深度内部文件
+ * （tsc 产出的 dist/knowledge/*、core/constraints/checker.js 等）不在清单——
+ * 它们非公开契约，存在性由 tsc 构建成功保证，历史上外部硬编码它们正是
+ * 重构误判（6cf3c329）的根因。
+ *
+ * 挂载点：harness release 命令第 4 步；studio publishPackage dist 校验（配套切换 studio#425）。
+ */
+export function verifyReleaseArtifacts(pkgRoot?: string): ArtifactIntegrityResult {
+  const root = resolveRoot(pkgRoot);
+  const checked = getCriticalArtifacts(root);
+  const missing = checked.filter(f => !fs.existsSync(path.join(root, f)));
+  return { ok: missing.length === 0, pkgRoot: root, checked, missing };
+}

package/src/test-setup/__tests__/mkdtemp-cleanup.test.ts

@@ -0,0 +1,45 @@
+/**
+ * mkdtemp 泄漏防护测试（2026-08-26 /tmp 3.9 万残留事故，与 studio 同款机制）。
+ * 正本见 ../mkdtemp-cleanup.ts。
+ */
+import fs from 'fs';
+import path from 'path';
+import {
+  patchMktempCleanup,
+  isRegisteredTmpDir,
+  sweepStaleMkdtempDirs,
+} from '../mkdtemp-cleanup';
+
+describe('mkdtemp-cleanup', () => {
+  it('patch 后 mkdtempSync 创建的目录进注册表（幂等）', () => {
+    patchMktempCleanup();
+    const d = fs.mkdtempSync(path.join('/tmp', 'harness-mkdtemp-cleanup-test-'));
+    expect(fs.existsSync(d)).toBe(true);
+    expect(isRegisteredTmpDir(d)).toBe(true);
+    fs.rmSync(d, { recursive: true, force: true });
+  });
+
+  it('sweep 只删超过年龄阈值且符合 mkdtemp 签名的目录', () => {
+    const base = fs.mkdtempSync(path.join('/tmp', 'harness-mkdtemp-cleanup-sweep-'));
+    const cases: Array<{ name: string; ageH: number; shouldRemove: boolean }> = [
+      { name: 'fake-test-aB3xY9', ageH: 25, shouldRemove: true }, // 签名匹配 + 超龄 -> 删
+      { name: 'fake-test-cD4zW0', ageH: 1, shouldRemove: false }, // 签名匹配但新鲜 -> 留
+      { name: 'org.chromium.Chromium.RJ5vUP', ageH: 25, shouldRemove: false }, // 含点（chrome crashpad）-> 不匹配
+      { name: 'fake-test-ab12', ageH: 25, shouldRemove: false }, // 后缀 4 字符 -> 不匹配
+      { name: 'tsx-0', ageH: 25, shouldRemove: false }, // 后缀 1 字符 -> 不匹配
+    ];
+    for (const c of cases) {
+      const p = path.join(base, c.name);
+      fs.mkdirSync(p);
+      const t = new Date(Date.now() - c.ageH * 3600 * 1000);
+      fs.utimesSync(p, t, t);
+    }
+
+    const removed = sweepStaleMkdtempDirs(base, 24 * 3600 * 1000);
+    expect(removed).toBe(1);
+    for (const c of cases) {
+      expect(fs.existsSync(path.join(base, c.name))).toBe(!c.shouldRemove);
+    }
+    fs.rmSync(base, { recursive: true, force: true });
+  });
+});

package/src/test-setup/mkdtemp-cleanup.ts

@@ -0,0 +1,83 @@
+/**
+ * Jest setupFilesAfterEnv - mkdtemp 泄漏防护（2026-08-26 /tmp 3.9 万残留事故根因修复）
+ *
+ * 事故：5 个测试文件 fs.mkdtempSync 后零清理（constraints-retire / check-drift /
+ * constraints-report / agent-prompt-renderer / injection-drift），日常 jest 运行累积。
+ *
+ * 机制（studio apps/api/tests/mkdtemp-cleanup.ts 同款，jest 版）：
+ * 1) patch fs.mkdtempSync--本进程创建的临时目录全部进注册表，afterAll 统一 rmSync。
+ *    jest worker 被 kill 时 process 'exit' 不触发，必须用 afterAll（setupFilesAfterEnv
+ *    里注册 = 文件级钩子）。
+ * 2) import 时清扫 tmpdir 里 >24h 且符合 mkdtemp 签名的目录，兜底 worker 被 kill 的场景。
+ *
+ * 签名正则只匹配「小写字母数字连字符前缀 + 恰好 6 位大小写字母数字后缀」：
+ * chrome crashpad（org.chromium.Chromium.XXXX，含点）、tsx-0 / jest_0 等不匹配。
+ */
+import fs from 'fs';
+import path from 'path';
+import { afterAll } from '@jest/globals';
+
+const MKDTEMP_SUFFIX_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-[A-Za-z0-9]{6}$/;
+
+let patched = false;
+const registeredDirs = new Set<string>();
+
+/** 幂等。setup 与测试文件重复调用安全。 */
+export function patchMktempCleanup(): void {
+  if (patched) return;
+  patched = true;
+  const orig = fs.mkdtempSync as (prefix: string) => string;
+  fs.mkdtempSync = ((prefix: string) => {
+    const dir = orig(prefix);
+    registeredDirs.add(dir);
+    return dir;
+  }) as typeof fs.mkdtempSync;
+
+  afterAll(() => {
+    for (const dir of registeredDirs) {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // 清理失败不阻断测试
+      }
+    }
+    registeredDirs.clear();
+  });
+}
+
+export function isRegisteredTmpDir(dir: string): boolean {
+  return registeredDirs.has(dir);
+}
+
+/**
+ * 清扫 tmpDir 中超龄且符合 mkdtemp 签名的目录。返回删除数。
+ * 单条失败（竞态被别进程先删等）不阻断。
+ */
+export function sweepStaleMkdtempDirs(tmpDir: string, ageMs: number): number {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(tmpDir);
+  } catch {
+    return 0;
+  }
+  const now = Date.now();
+  let removed = 0;
+  for (const name of entries) {
+    if (!MKDTEMP_SUFFIX_RE.test(name)) continue;
+    try {
+      const p = path.join(tmpDir, name);
+      const st = fs.statSync(p);
+      if (st.isDirectory() && now - st.mtimeMs > ageMs) {
+        fs.rmSync(p, { recursive: true, force: true });
+        removed++;
+      }
+    } catch {
+      // 单条竞态不阻断
+    }
+  }
+  return removed;
+}
+
+// setupFilesAfterEnv 顶层执行：打补丁 + 清扫历史残留
+patchMktempCleanup();
+sweepStaleMkdtempDirs(process.env.TMPDIR || '/tmp', 24 * 60 * 60 * 1000);

package/src/types/failure.ts

@@ -5,6 +5,14 @@
  * 不包含业务逻辑，只定义数据结构
  */
 
+/**
+ * 默认 failure 日志路径（相对项目根目录）
+ *
+ * 读写双方必须统一引用此常量（DEFAULT_TRACE_FILE 同款先例）；
+ * 自定义路径时向 FailureRecorder 传入自定 logFile
+ */
+export const DEFAULT_FAILURE_LOG_FILE = '.harness/logs/failures.log';
+
 /**
  * 错误类型枚举
  */