@dommaker/harness 1.6.0 → 1.8.0

package/src/monitoring/traces.ts

@@ -21,6 +21,9 @@ import {
 
 /**
  * 默认配置
+ *
+ * `traceFile` 这里是**未锚定的项目相对片段**（#95 病根形状），故本文件在
+ * `project-path-convention.test.ts` 闸 3 的豁免表里点名带理由；锚定动作在构造函数里做。
  */
 const DEFAULT_CONFIG: TraceCollectorConfig = {
   traceFile: DEFAULT_TRACE_FILE,
@@ -33,7 +36,7 @@ const DEFAULT_CONFIG: TraceCollectorConfig = {
  *
  * 使用方式：
  * ```typescript
- * const collector = new TraceCollector();
+ * const collector = new TraceCollector({ projectPath: '/path/to/project' });
  * collector.record({
  *   constraintId: 'no_fix_without_root_cause',
  *   level: 'iron_law',
@@ -48,7 +51,11 @@ export class TraceCollector {
 
   constructor(config?: Partial<TraceCollectorConfig>) {
     this.config = { ...DEFAULT_CONFIG, ...config };
-    this.traceFile = this.config.traceFile!;
+    // 收根则相对落点按项目解析（harness#139：否则 -p 半失效——评估跑在 B、trace 写进 cwd）；
+    // 没收根则保持 cwd 解析，这是跨仓消费者（studio）依赖的兼容面，不是遗漏
+    this.traceFile = this.config.projectPath
+      ? path.resolve(this.config.projectPath, this.config.traceFile!)
+      : this.config.traceFile!;
     this.ensureDirectory();
   }
 
@@ -304,12 +311,17 @@ export class TraceCollector {
 }
 
 /**
- * 全局单例（可选）
+ * 全局单例（**cwd 锚定**的兼容面）
+ *
+ * harness#139 起本仓生产代码不再消费它：CLI check/report 与 bootstrap 四个组合根
+ * 各自 `new TraceCollector({ projectPath })` 锚根构造（守卫见 project-path-convention
+ * 闸 4）。保留是给跨仓调用方（studio）的既有形状——它依赖「API 进程 cwd 恰好是项目」。
+ * 传 `projectPath` 是它的锚根出口；不传则落点按 cwd 解析（行为逐字不变）。
  */
 let globalCollector: TraceCollector | null = null;
 
 /**
- * 获取全局收集器
+ * 获取全局收集器（cwd 锚定，兼容语义见上）
  */
 export function getTraceCollector(): TraceCollector {
   if (!globalCollector) {
@@ -319,7 +331,9 @@ export function getTraceCollector(): TraceCollector {
 }
 
 /**
- * 配置全局收集器
+ * 配置全局收集器（cwd 锚定，兼容语义见 `getTraceCollector()`）
+ *
+ * 需要把 trace 落进指定项目的调用方直接构造实例：`new TraceCollector({ projectPath })`。
  */
 export function configureTraceCollector(config: Partial<TraceCollectorConfig>): void {
   globalCollector = new TraceCollector(config);

package/src/release/CONTEXT.md

@@ -16,7 +16,7 @@
 ## 约定
 - 清单维护模型：声明面推导为主（目录重构动到 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 时该测试强制同步
+- `__tests__/integrity.test.ts` 的「真实包根清单同步闸门」是重构同步闸门，对完整清单做显式期望 `toEqual` 精确对撞（#160 起双向成立）：声明面（`exports`/`main`/`bin`）增、删、改任一条目都变红并指名差额项，动声明面必须同步测试内的显式清单；extras 由同文件另一条 `toEqual` 精确冻结，闸门内展开引用保持单一来源
 - bin 新增引导期 require 的 dist 文件 → extras 加一条 + 测试同步
 
 ## 注意事项

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

@@ -139,19 +139,28 @@ describe('getCriticalArtifacts / verifyReleaseArtifacts（fixture 包根）', ()
 });
 
 describe('真实包根清单同步闸门', () => {
-  it('真实 package.json 推导覆盖全部声明入口 + extras（重构动声明面时本测试强制同步）', () => {
+  it('真实 package.json 推导清单与显式期望精确相等（声明面增/删/改任一条目本测试强制同步，#160）', () => {
     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);
-    }
+    // 双向对撞：toContain 只钉得住删/改，新增声明条目会静默多出——故用 toEqual 显式清单
+    // （ADR-0003 公共面冻结闸同形）。getCriticalArtifacts 返回已排序数组，期望侧同口径 .sort()。
+    expect(artifacts).toEqual(
+      [
+        // 声明面（main/exports/bin）推导的脚本入口：动 package.json 声明面须同步本清单
+        'bin/harness.js',
+        'dist/context/index.d.ts',
+        'dist/context/index.js',
+        'dist/core/index.d.ts',
+        'dist/core/index.js',
+        'dist/gates/index.d.ts',
+        'dist/gates/index.js',
+        'dist/index.d.ts',
+        'dist/index.js',
+        'dist/presets/index.d.ts',
+        'dist/presets/index.js',
+        // extras 单一来源在 integrity.ts，另由上方 toEqual 用例精确冻结，此处展开引用不复制
+        ...EXTRA_CRITICAL_ARTIFACTS,
+      ].sort(),
+    );
   });
 });

package/src/test-setup/__tests__/jsonl-fake-fs.test.ts

@@ -0,0 +1,98 @@
+/**
+ * 有界读 fs 假件测试（ADR-0023 决策 3 的夹具层）
+ *
+ * 钉的是夹具的契约：它给出的字节视图必须与 `readFile(path)` 的字符串**逐项等价**、且
+ * **跟着 openSync 的路径走**。两条读入口一旦各演一份世界，被测代码的容错分支会把不一致
+ * 吞成假象（本夹具存在的理由就是消灭这类假象）。
+ */
+
+import { jsonlBoundedReadChain } from '../jsonl-fake-fs';
+
+describe('jsonlBoundedReadChain', () => {
+  it('fstatSync 的 size 是所开文件的 UTF-8 字节数，不是字符数', () => {
+    const text = '{"n":1,"文本":"约束"}\n';
+    const chain = jsonlBoundedReadChain(() => text);
+    const fd = chain.openSync('/x/a.jsonl', 'r');
+    expect(chain.fstatSync(fd).size).toBe(Buffer.byteLength(text, 'utf-8'));
+    expect(chain.fstatSync(fd).size).toBeGreaterThan(text.length);
+  });
+
+  it('readSync 按 position/length 取窗口并回填缓冲，返回实际读到的字节数', () => {
+    const chain = jsonlBoundedReadChain(() => 'abcdef\nghijkl\n');
+    const fd = chain.openSync('/x/a.jsonl');
+    const buf = Buffer.alloc(7);
+    expect(chain.readSync(fd, buf, 0, 7, 7)).toBe(7);
+    expect(buf.toString('utf-8')).toBe('ghijkl\n');
+  });
+
+  it('越界的 length 只拷到文件末尾，超出 EOF 读到 0 字节', () => {
+    const chain = jsonlBoundedReadChain(() => 'ab\n');
+    const fd = chain.openSync('/x/a.jsonl');
+    const tail = Buffer.alloc(4);
+    expect(chain.readSync(fd, tail, 0, 4, 1)).toBe(2);
+    expect(tail.subarray(0, 2).toString('utf-8')).toBe('b\n');
+    expect(chain.readSync(fd, Buffer.alloc(2), 0, 2, 99)).toBe(0);
+  });
+
+  it('offset 让调用方把多块拼进同一缓冲（分块读的形状）', () => {
+    const chain = jsonlBoundedReadChain(() => '0123456789');
+    const fd = chain.openSync('/x/a.jsonl');
+    const buf = Buffer.alloc(6);
+    chain.readSync(fd, buf, 0, 4, 0);
+    chain.readSync(fd, buf, 4, 2, 4);
+    expect(buf.toString('utf-8')).toBe('012345');
+  });
+
+  it('按路径分派内容：同一次运行开两个文件，各自读到自己的那份', () => {
+    const files: Record<string, string> = {
+      '/s/1/checkpoint.json': '{"id":"cp-1"}\n',
+      '/s/1/events.jsonl': '{"type":"user_message"}\n{"type":"assistant_message"}\n',
+    };
+    const chain = jsonlBoundedReadChain(p => files[p] ?? '');
+    const fdA = chain.openSync('/s/1/checkpoint.json');
+    const fdB = chain.openSync('/s/1/events.jsonl');
+    expect(chain.fstatSync(fdA).size).toBe(Buffer.byteLength(files['/s/1/checkpoint.json']));
+    expect(chain.fstatSync(fdB).size).toBe(Buffer.byteLength(files['/s/1/events.jsonl']));
+    const buf = Buffer.alloc(64);
+    const n = chain.readSync(fdB, buf, 0, 64, 0);
+    expect(buf.subarray(0, n).toString('utf-8')).toBe(files['/s/1/events.jsonl']);
+  });
+
+  it('未开过的 fd 与 close 掉的 fd 都按空文件处理，不互相串内容', () => {
+    // 内容源必须按路径分派：不看路径的源会让「路径丢失」这条失效模式测不出来
+    const files: Record<string, string> = { '/x/a.jsonl': 'x\ny\n' };
+    const chain = jsonlBoundedReadChain(p => files[p] ?? '');
+    const fd = chain.openSync('/x/a.jsonl');
+    expect(chain.fstatSync(fd).size).toBe(4);
+    chain.closeSync(fd);
+    expect(chain.fstatSync(fd).size).toBe(0);
+    expect(chain.fstatSync(999).size).toBe(0);
+  });
+
+  it('内容每次现取：改了 readFile 的返回，下一次读立即看到', () => {
+    let value = 'first\n';
+    const chain = jsonlBoundedReadChain(() => value);
+    const fd = chain.openSync('/x/a.jsonl');
+    expect(chain.fstatSync(fd).size).toBe(6);
+    value = 'second-longer\n';
+    expect(chain.fstatSync(fd).size).toBe(14);
+    const buf = Buffer.alloc(14);
+    chain.readSync(fd, buf, 0, 14, 0);
+    expect(buf.toString('utf-8')).toBe('second-longer\n');
+  });
+
+  it('非字符串内容按空文件处理（mock 未设置返回值时的缺省形状）', () => {
+    for (const raw of [undefined, null, 0]) {
+      const chain = jsonlBoundedReadChain(() => raw);
+      const fd = chain.openSync('/x/a.jsonl');
+      expect(chain.fstatSync(fd).size).toBe(0);
+      expect(chain.readSync(fd, Buffer.alloc(3), 0, 3, 0)).toBe(0);
+    }
+  });
+
+  it('openSync 每次发新 fd，多次开关不冲突', () => {
+    const chain = jsonlBoundedReadChain(() => 'a\n');
+    const fds = [chain.openSync('/x/a.jsonl'), chain.openSync('/x/a.jsonl')];
+    expect(new Set(fds).size).toBe(2);
+  });
+});

package/src/test-setup/jsonl-fake-fs.ts

@@ -0,0 +1,59 @@
+/**
+ * JSONL 有界读的 fs 假件（测试夹具层）
+ *
+ * 背景：`utils/jsonl` 的 tail/head 是分块有界读（`openSync` + `fstatSync` + `readSync` +
+ * `closeSync`，ADR-0023 决策 3）。把整个 `fs` 模块 mock 掉的测试原先只提供了全文读入口
+ * `readFileSync`，于是走有界读的被测代码直接抛错，再被它自己的 `catch` 吞成「数据不存在」
+ * 一类的假象（session-manager 报 `Checkpoint 不存在`、context-tracker 读出空快照都是这样）。
+ *
+ * 口径一（同源）：内容经 `readFile(path)` 现取，直接把 `readFileSync` 那个 mock 包一层即可——
+ * 测试改了它的返回值，两条读入口看到的就是同一个文件。
+ * 口径二（按路径分派）：`openSync` 收到的路径必须传到后面三次调用上。有的假件按路径参数
+ * 冒充多个文件（`if (p.includes('events.jsonl')) ...`），丢了路径就会读到别的文件或直接空。
+ */
+
+/** 有界读用到的四个 fs 入口，形状与 `fs` 对应函数一致 */
+export interface BoundedReadChain {
+  openSync: (path: string, flags?: string) => number;
+  fstatSync: (fd: number) => { size: number };
+  readSync: (
+    fd: number,
+    buffer: Buffer,
+    offset: number,
+    length: number,
+    position: number
+  ) => number;
+  closeSync: (fd: number) => void;
+}
+
+/**
+ * 以 `readFile(path)` 为唯一内容源，凑出有界读所需的四个 fs 入口
+ *
+ * 非字符串（含 mock 未设置时的 `undefined`）按空文件处理。不用 `jest.fn()` 包：本夹具只需
+ * 行为正确；要数调用次数，在调用点自己套一层。
+ */
+export function jsonlBoundedReadChain(readFile: (path: string) => unknown): BoundedReadChain {
+  const bytesOf = (path: string): Buffer => {
+    const raw = readFile(path);
+    return Buffer.from(typeof raw === 'string' ? raw : '', 'utf-8');
+  };
+  const openPaths = new Map<number, string>();
+  let nextFd = 100;
+  return {
+    openSync: path => {
+      const fd = nextFd++;
+      openPaths.set(fd, String(path));
+      return fd;
+    },
+    fstatSync: fd => ({ size: bytesOf(openPaths.get(fd) ?? '').length }),
+    readSync: (fd, buffer, offset, length, position) => {
+      const bytes = bytesOf(openPaths.get(fd) ?? '');
+      // 真 readSync 在 position 越过 EOF 时返回 0；Buffer.copy 遇 sourceStart 超范围会抛
+      if (position >= bytes.length) return 0;
+      return bytes.copy(buffer, offset, position, position + length);
+    },
+    closeSync: fd => {
+      openPaths.delete(fd);
+    },
+  };
+}

package/src/tools/index.ts

@@ -1 +1,5 @@
-export * from './paths';
+/**
+ * Tools 模块导出（ADR-0003：显式清单，禁 export *，harness#137）
+ */
+
+export { getToolsDir, getRegistryPath } from './paths';

package/src/types/checkpoint.ts

@@ -171,4 +171,10 @@ export interface CheckpointContext {
   
   /** 自定义检查处理器 */
   customHandlers?: Map<string, (config: CheckConfig) => Promise<CheckResult>>;
+  
+  /**
+   * 重试退避的等待注入（http_* 检查族消费）
+   * 缺省 = 真定时器；测试可注入零等待替身，据此断言重试语义而不必真等
+   */
+  sleep?: (ms: number) => Promise<void>;
 }

package/src/types/passes-gate.ts

@@ -55,23 +55,6 @@ export interface TaskTestResult {
   evidence?: string;
 }
 
-/**
- * 动态任务（用于 passes-gate）
- */
-export interface DynamicTask {
-  /** 任务 ID */
-  id: string;
-  
-  /** 任务名称 */
-  name?: string;
-  
-  /** 是否通过 */
-  passes?: boolean;
-  
-  /** 测试结果 */
-  testResult?: TaskTestResult;
-}
-
 // ========================================
 // AS-006: 纯约束验证接口
 // ========================================

package/src/types/project-config.ts

@@ -224,6 +224,24 @@ export interface GovernanceConfig {
   testing?: TestingGovernanceConfig;
 }
 
+/**
+ * CI 平台（harness#143）：服务端门禁的接线目标
+ *
+ * 本地 hook 跑在推送者控制的机器上（`--no-verify` 可绕过），只能算自检；
+ * 真正的门禁必须抢到服务端 CI 这个执行时机。取值域另含 `'none'`（不接线），
+ * 那在本类型之外——命令层据此让 CI 站点干脆不进 plan，scaffold 只见有形状的平台。
+ */
+export type CiPlatform = 'github' | 'gitlab';
+
+/**
+ * CI 接线配置（config.yml `ci` 段，harness#143）
+ *
+ * `platform` 缺省 = `github`；`'none'` = 不落任何 CI 文件。旧配置无此段即 `github`，零迁移。
+ */
+export interface CiConfig {
+  platform?: CiPlatform | 'none';
+}
+
 /**
  * 项目配置
  */
@@ -236,6 +254,9 @@ export interface ProjectConfig {
   /** 使用预设 */
   preset?: 'strict' | 'standard' | 'relaxed';
 
+  /** CI 接线平台（harness#143，缺省 github） */
+  ci?: CiConfig;
+
   /**
    * 项目适用场景标签（ADR-0001，如 'agent-skill'、'llm-app'）
    *

package/src/types/trace.ts

@@ -5,10 +5,11 @@
  */
 
 /**
- * 默认 trace 文件路径（相对项目根目录）
+ * 默认 trace 文件路径（项目相对片段——**不是**可直接打开的路径）
  *
- * 读写双方必须统一引用此常量；
- * 需要自定义路径时使用 configureTraceCollector / TraceCollectorConfig.traceFile
+ * 读写双方都必须把它锚到项目根（`path.resolve(projectPath, DEFAULT_TRACE_FILE)`，
+ * harness#139）。采集器侧的锚定在 `TraceCollector` 构造内完成（传 `projectPath` 即可）；
+ * 需要自定义路径时使用 `TraceCollectorConfig.traceFile`（相对值同样按 projectPath 解析）。
  */
 export const DEFAULT_TRACE_FILE = '.harness/logs/traces.log';
 
@@ -197,7 +198,16 @@ export interface TraceFilter {
  * Trace 收集器配置
  */
 export interface TraceCollectorConfig {
-  /** Trace 文件路径 */
+  /**
+   * 项目根（harness#139，#95 约定的落地形状）
+   *
+   * 给了 → 缺省/相对的 `traceFile` 按它解析（`path.resolve(projectPath, traceFile)`），
+   * 从别处带 `--project-path` 跑时 trace 落进目标项目；
+   * 不给 → 保持 cwd 解析现状（跨仓消费者的兼容面，不是遗漏）。
+   */
+  projectPath?: string;
+
+  /** Trace 文件路径（绝对值原样；相对值按 projectPath 解析，无 projectPath 时按 cwd） */
   traceFile?: string;
 
   /** 最大文件大小（字节），超出则滚动 */

package/src/utils/__tests__/file-walk.test.ts

@@ -4,13 +4,14 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import { findTsSourceFiles } from '../file-walk';
 
 describe('findTsSourceFiles', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-file-walk');
+  let tempDir: string;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-file-walk-'));
   });
 
   afterAll(() => {

package/src/utils/__tests__/jsonl-bounded-read.test.ts

@@ -0,0 +1,106 @@
+/**
+ * 有界读的「不整读全文」闸（ADR-0023 决策 3：tail 倒读，并同型推广到 head 正读）
+ *
+ * 单独成文件的理由：Node 的 `fs` 导出属性不可 redefine，`jest.spyOn(fs, 'readFileSync')`
+ * 直接抛 `Cannot redefine property`——只能在模块解析层把 `readFileSync` 换成必炸实现，
+ * 其余 fs 行为经 requireActual 保真（两条有界读用的 openSync/fstatSync/readSync 都是真的）。
+ *
+ * 反向断言（全文读必须炸）是这道闸的自我检查：没有它，「有界读通过」可能只是 mock 没生效。
+ */
+
+jest.mock('fs', () => ({
+  ...jest.requireActual('fs'),
+  readFileSync: () => {
+    throw new Error('整读全文：有界读消费方不该走到这条路径');
+  },
+}));
+
+import * as path from 'path';
+import { readJsonl } from '../jsonl';
+
+interface Row {
+  n: number;
+}
+
+const realFs = jest.requireActual('fs');
+const realOs = jest.requireActual('os');
+
+describe('readJsonl 有界读', () => {
+  let dir: string;
+  let filePath: string;
+
+  beforeAll(() => {
+    dir = realFs.mkdtempSync(path.join(realOs.tmpdir(), 'harness-bounded-read-'));
+    // 20 万行 ≈ 4MB，远超 64KB 分块：整读要把它全捞进内存，有界读只需捞一端
+    const lines = Array.from({ length: 200000 }, (_, i) => `{"n":${i}}`);
+    filePath = path.join(dir, 'big.jsonl');
+    realFs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
+  });
+
+  afterAll(() => {
+    realFs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('mock 生效：全文读确实走 readFileSync（必炸）', () => {
+    expect(() => readJsonl<Row>(filePath, 'skip')).toThrow('整读全文');
+  });
+
+  it('tail 只要够数的尾部行，不整读全文', () => {
+    const { records, skippedLines } = readJsonl<Row>(filePath, 'throw', { tail: 3 });
+    expect(skippedLines).toBe(0);
+    expect(records.map(r => r.n)).toEqual([199997, 199998, 199999]);
+  });
+
+  it('head 只要够数的头部行，不整读全文', () => {
+    const { records, skippedLines } = readJsonl<Row>(filePath, 'throw', { head: 3 });
+    expect(skippedLines).toBe(0);
+    expect(records.map(r => r.n)).toEqual([0, 1, 2]);
+  });
+
+  it('head：跨 64KB 块边界的多字节字符不被切断', () => {
+    const wide = path.join(dir, 'wide.jsonl');
+    const lines = Array.from(
+      { length: 1200 },
+      (_, i) => JSON.stringify({ n: i, 文本: '约束进化飞轮'.repeat(12) })
+    );
+    realFs.writeFileSync(wide, lines.join('\n') + '\n', 'utf-8');
+    expect(realFs.statSync(wide).size).toBeGreaterThan(64 * 1024);
+    const { records, skippedLines } = readJsonl<{ n: number; 文本: string }>(wide, 'throw', {
+      head: 2,
+    });
+    expect(skippedLines).toBe(0);
+    expect(records.map(r => r.n)).toEqual([0, 1]);
+    expect(records[1].文本).toBe('约束进化飞轮'.repeat(12));
+  });
+
+  it('两端超过总行数时取全部', () => {
+    const small = path.join(dir, 'small.jsonl');
+    realFs.writeFileSync(small, '{"n":1}\n{"n":2}\n', 'utf-8');
+    expect(readJsonl<Row>(small, 'throw', { tail: 50 }).records.map(r => r.n)).toEqual([1, 2]);
+    expect(readJsonl<Row>(small, 'throw', { head: 50 }).records.map(r => r.n)).toEqual([1, 2]);
+  });
+
+  it('head: 0 与缺文件返回空结果，不打开文件', () => {
+    const few = path.join(dir, 'few.jsonl');
+    realFs.writeFileSync(few, '{"n":1}\n', 'utf-8');
+    expect(readJsonl<Row>(few, 'skip', { head: 0 })).toEqual({ records: [], skippedLines: 0 });
+    expect(readJsonl<Row>(path.join(dir, 'missing.jsonl'), 'skip', { head: 5 })).toEqual({
+      records: [],
+      skippedLines: 0,
+    });
+  });
+
+  it('head 的槽位口径与整读一致：坏行占一个尾部槽位、不进 records', () => {
+    const dirty = path.join(dir, 'dirty.jsonl');
+    realFs.writeFileSync(dirty, 'not-json\n{"n":2}\n{"n":3}\n', 'utf-8');
+    const { records, skippedLines } = readJsonl<Row>(dirty, 'skip', { head: 2 });
+    expect(skippedLines).toBe(1);
+    expect(records.map(r => r.n)).toEqual([2]);
+  });
+
+  it('末行无换行时 head 也能取到它', () => {
+    const noEol = path.join(dir, 'no-eol.jsonl');
+    realFs.writeFileSync(noEol, '{"n":1}\n{"n":2}', 'utf-8');
+    expect(readJsonl<Row>(noEol, 'throw', { head: 2 }).records.map(r => r.n)).toEqual([1, 2]);
+  });
+});

package/src/utils/__tests__/jsonl-skip-disposition.test.ts

@@ -17,9 +17,11 @@
  * 裁决——否则「改成 throw 就免掉告知」成了原则的绕行通道。`src/utils/jsonl.ts` 本身是策略
  * 定义处，排除。
  * `readJsonlEnds`（首尾读取）同样是 skip 读点，纳入同一识别正则——否则它成为本契约的
- * 绕行通道（harness#114）。
- * `countJsonlLines` 的纯行数站点（如 `check` 的提示计数）不 parse、不产坏行计数，也不在本表内
- * ——它把损坏行算进条数的问题属口径变更，#100 明确不做。
+ * 绕行通道（harness#114）。`readJsonlWindow`（尾部窗口，ADR-0023 供一次运行内多个
+ * 尾部消费方共用一份行文本）同判据纳入。
+ * `countJsonlLines`（纯计数入口，把坏行算进条数却不 parse）已随其唯一消费点——`check` 的
+ * 提示阈值——改用有界 `head` 读而删除（ADR-0023 决策 3 推广）；该消费点因此成为本表内的
+ * skip 站点，按契约就地记名豁免。
  */
 
 import * as fs from 'fs';
@@ -41,9 +43,10 @@ const POLICY_WINDOW_LINES = 6;
  * 每个读点的去向理由在调用点注释里，此表只钉「有哪些点、各几处」。
  */
 const EXPECTED_SKIP_READ_SITES: Record<string, number> = {
+  'src/cli/commands/check.ts': 1,
   'src/cli/commands/status.ts': 1,
   'src/context/session-manager.ts': 2,
-  'src/core/constraints/context-builder.ts': 2,
+  'src/core/constraints/run-env.ts': 1,
   'src/core/constraints/usage-report.ts': 1,
   'src/failure/recorder.ts': 1,
   'src/knowledge/reference-tracker.ts': 1,
@@ -79,7 +82,7 @@ interface CallSite {
 }
 
 /**
- * 找出一个文件里所有 readJsonl 调用点并判出坏行策略。
+ * 找出一个文件里所有 readJsonl 系读点并判出坏行策略。
  * 调用参数可能换行，故从 `readJsonl` 起拼若干行再判：先遇到 `'skip'` 记 skip、
  * 先遇到 `'throw'` 记 throw，两者都不出现记 unknown。
  */
@@ -89,7 +92,8 @@ function callSites(file: string): CallSite[] {
 
   for (let i = 0; i < raw.length; i++) {
     const trimmed = raw[i].trim();
-    if (!/readJsonl(?:Ends)?\s*[<(]/.test(trimmed)) continue;
+    // Window 同纳入：否则「改用尾部窗口读」成为 skip 契约的逃逸通道（harness#114 同一手法）
+    if (!/readJsonl(?:Ends|Window)?\s*[<(]/.test(trimmed)) continue;
     // 注释行里的示例不是站点（策略定义处 src/utils/jsonl.ts 已整体排除）
     if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
 

package/src/utils/__tests__/jsonl.test.ts

@@ -5,7 +5,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { readJsonl, countJsonlLines, readJsonlEnds, appendJsonl } from '../jsonl';
+import { readJsonl, readJsonlEnds, appendJsonl } from '../jsonl';
 
 interface Row {
   n: number;
@@ -88,24 +88,71 @@ describe('readJsonl', () => {
     expect(readJsonl<Row>(filePath, 'skip', { tail: 10 }).records).toHaveLength(1);
     expect(readJsonl<Row>(filePath, 'skip', { head: 10 }).records).toHaveLength(1);
   });
-});
 
-describe('countJsonlLines', () => {
-  let dir: string;
+  // ===== tail 倒读（ADR-0023 决策 3）：语义必须与「整读后 slice」逐字一致 =====
+
+  it('tail：与整读后截断的结果逐字等价', () => {
+    const filePath = write('equiv.jsonl', ['{"n":1}', CORRUPT, '', '{"n":4}', '  ', '{"n":6}']);
+    const whole = readJsonl<Row>(filePath, 'skip');
+    const tail = readJsonl<Row>(filePath, 'skip', { tail: 3 });
+    // 末尾 3 个非空行含 1 个坏行 → records 只剩 2 条，坏行照旧计入 skippedLines
+    expect(tail.records).toEqual(whole.records.slice(-2));
+    expect(tail.records.map(r => r.n)).toEqual([4, 6]);
+    expect(tail.skippedLines).toBe(1);
+  });
+
+  it('tail：跨 64KB 块边界的多字节字符不被切断', () => {
+    // 每行含 CJK，行数足够跨过若干个分块边界；残段按字节留到下一轮才解码
+    const lines = Array.from(
+      { length: 1200 },
+      (_, i) => JSON.stringify({ n: i, 文本: '约束进化飞轮'.repeat(12) })
+    );
+    const filePath = write('wide.jsonl', lines);
+    expect(fs.statSync(filePath).size).toBeGreaterThan(64 * 1024);
+    const { records, skippedLines } = readJsonl<{ n: number; 文本: string }>(
+      filePath,
+      'throw',
+      { tail: 5 }
+    );
+    expect(skippedLines).toBe(0);
+    expect(records.map(r => r.n)).toEqual([1195, 1196, 1197, 1198, 1199]);
+    expect(records[0].文本).toBe('约束进化飞轮'.repeat(12));
+  });
 
-  beforeEach(() => {
-    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
+  it('tail：末行无换行也能取到', () => {
+    const filePath = path.join(dir, 'no-eol.jsonl');
+    fs.writeFileSync(filePath, '{"n":1}\n{"n":2}', 'utf-8');
+    expect(readJsonl<Row>(filePath, 'skip', { tail: 1 }).records.map(r => r.n)).toEqual([2]);
   });
 
-  afterEach(() => {
-    fs.rmSync(dir, { recursive: true, force: true });
+  it('tail：CRLF 的 \\r 随行进文本，parse 照旧通过', () => {
+    const filePath = path.join(dir, 'crlf.jsonl');
+    fs.writeFileSync(filePath, '{"n":1}\r\n{"n":2}\r\n', 'utf-8');
+    expect(readJsonl<Row>(filePath, 'throw', { tail: 2 }).records.map(r => r.n)).toEqual([1, 2]);
+  });
+
+  it('tail：文件尾部的纯空白行不计数，继续往前找够数', () => {
+    const filePath = write('blank-tail.jsonl', ['{"n":1}', '{"n":2}', '', '   ', '\t']);
+    expect(readJsonl<Row>(filePath, 'skip', { tail: 2 }).records.map(r => r.n)).toEqual([1, 2]);
+  });
+
+  it('tail：走倒读分块，不整读全文——见 jsonl-tail-seek.test.ts（fs 导出属性不可 redefine，只能在模块层 mock）', () => {
+    const filePath = write('seek.jsonl', Array.from({ length: 5000 }, (_, i) => `{"n":${i}}`));
+    expect(readJsonl<Row>(filePath, 'skip', { tail: 2 }).records.map(r => r.n)).toEqual([
+      4998, 4999,
+    ]);
   });
 
-  it('计非空行数（含坏行），缺文件为 0', () => {
-    const filePath = path.join(dir, 'c.jsonl');
-    fs.writeFileSync(filePath, ['{"n":1}', CORRUPT, '', '  '].join('\n') + '\n', 'utf-8');
-    expect(countJsonlLines(filePath)).toBe(2);
-    expect(countJsonlLines(path.join(dir, 'missing.jsonl'))).toBe(0);
+  it('tail: 0 与缺文件均返回空结果，不打开文件', () => {
+    const filePath = write('zero.jsonl', ['{"n":1}']);
+    expect(readJsonl<Row>(filePath, 'skip', { tail: 0 })).toEqual({
+      records: [],
+      skippedLines: 0,
+    });
+    expect(readJsonl<Row>(path.join(dir, 'missing.jsonl'), 'skip', { tail: 5 })).toEqual({
+      records: [],
+      skippedLines: 0,
+    });
   });
 });
 
@@ -172,7 +219,7 @@ describe('appendJsonl', () => {
     appendJsonl(filePath, { n: 1 });
     appendJsonl(filePath, { n: 2 });
 
-    expect(countJsonlLines(filePath)).toBe(2);
+    expect(readJsonl<Row>(filePath, 'skip').records.map(r => r.n)).toEqual([1, 2]);
     const lines = fs.readFileSync(filePath, 'utf-8').split('\n');
     expect(lines[0]).toBe('{"n":1}');
     expect(lines[1]).toBe('{"n":2}');