@dommaker/harness 1.6.0 → 1.8.0

package/src/cli/commands/sync-docs/index.ts

@@ -7,7 +7,7 @@
  * 实现拆分：
  * - project-reader.ts       项目信息读取（package.json/config.yml/源码扫描）
  * - capabilities-syncer.ts  CAPABILITIES.md 文件表格格式的对比与维护（能力清单格式解析/计数走 core/constraints/capabilities-parser）
- * - context-syncer.ts       CONTEXT.md 模板生成/发现/过时判定
+ * - context-syncer.ts       CONTEXT.md 模板生成/发现/过时判定 + 目录导出面采集（harness#142）
  * - agents-syncer.ts        AGENTS.md 生成
  * - preserve-block.ts       PRESERVE 标记块提取与组合
  */
@@ -25,6 +25,7 @@ import {
 import { COMMAND_DEFINITIONS } from '../definitions';
 import { GATE_DEFINITIONS } from '../../../gates/definitions';
 import { reconcileCapabilities } from '../../../core/constraints/capabilities-reconcile';
+import { reconcileContext } from '../../../core/constraints/context-reconcile';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
 import { getCapabilitiesMode } from '../../../core/project-config-loader';
 import { getSourceDirs, scanSourceModules, getRequiredContextDirs } from './project-reader';
@@ -34,7 +35,12 @@ import {
   updateCapabilitiesFile,
   compactCapabilitiesContent,
 } from './capabilities-syncer';
-import { createContextMd, findExistingContextFiles, getLatestTsMtime } from './context-syncer';
+import {
+  createContextMd,
+  findExistingContextFiles,
+  getLatestTsMtime,
+  collectContextExportSurface,
+} from './context-syncer';
 import { buildAgentsMd } from './agents-syncer';
 import { extractPreserveBlocks, composeAgentsMd } from './preserve-block';
 import { log, processIO, type CommandIO, type CommandResult } from '../../command-contract';
@@ -111,23 +117,12 @@ export async function syncDocs(
     removed: [],
     contextMissing: [],
     contextStale: [],
+    contextContentDrift: [],
   };
 
-  // 1. 扫描源码模块（从 governance config 读取目录列表，默认 src/）
+  // 1. 先判定本次运行需要什么：源码目录列表 + 现有 CAPABILITIES.md 的格式
+  //    （格式判定必须在扫描之前——它决定下面那份清单要不要去取）
   const srcDirs = await getSourceDirs(projectPath);
-  const currentModules: ModuleInfo[] = [];
-  for (const srcDir of srcDirs) {
-    try {
-      const modules = await scanSourceModules(path.join(projectPath, srcDir), projectPath);
-      currentModules.push(...modules);
-    } catch {
-      if (!isJson) {
-        log(io, chalk.yellow(`⚠️  未找到 ${srcDir} 目录，跳过`));
-      }
-    }
-  }
-
-  // 2. 解析现有 CAPABILITIES.md，检测格式
   const capabilitiesPath = path.join(projectPath, 'CAPABILITIES.md');
   let existingFiles: string[] = [];
   let capsContent = '';
@@ -144,6 +139,23 @@ export async function syncDocs(
     // CAPABILITIES.md 不存在，将创建
   }
 
+  // 2. 扫描源码模块（从 governance config 读取目录列表，默认 src/）
+  // capability-listing 格式不做条目级比对（计数才是判定面），模块清单在本次运行里无人
+  // 消费 → 整树一份 .ts 内容都不读（harness#147；改造前是无条件全树逐文件读首行注释）。
+  const currentModules: ModuleInfo[] = [];
+  if (!capsIsCapabilityListing) {
+    for (const srcDir of srcDirs) {
+      try {
+        const modules = await scanSourceModules(path.join(projectPath, srcDir), projectPath);
+        currentModules.push(...modules);
+      } catch {
+        if (!isJson) {
+          log(io, chalk.yellow(`⚠️  未找到 ${srcDir} 目录，跳过`));
+        }
+      }
+    }
+  }
+
   // 3. 对比差异（分两种格式）
   let capCountMismatches: string[] = [];
 
@@ -176,7 +188,11 @@ export async function syncDocs(
     result.removed = verdict.deadEntries;
   }
 
-  // 4. 检查 CONTEXT.md（缺失 + 过时）
+  // 4. 检查 CONTEXT.md（缺失 + 内容漂移 + mtime 提示）
+  // CI 标志：CI runner 上是全新 checkout，mtime 由 clone 顺序决定（同目录 CONTEXT.md 排序
+  // 恒先于 .ts），比出来的「过时」是假灯（harness#142 实测证据）→ 连提示都不给。
+  const isCi = Boolean(process.env.CI) && process.env.CI !== 'false';
+
   // 4a. 配置中要求的目录：检查缺失
   const contextDirs = await getRequiredContextDirs(projectPath);
   for (const dir of contextDirs) {
@@ -188,16 +204,35 @@ export async function syncDocs(
     }
   }
 
-  // 4b. 自动发现已有的 CONTEXT.md：检查过时
+  // 4b. 自动发现已有的 CONTEXT.md：内容判定（漂移 = 判定面）+ mtime（仅本地提示）
   const existingContextFiles = await findExistingContextFiles(projectPath, srcDirs);
   for (const dir of existingContextFiles) {
     const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
     try {
-      const contextStat = await fs.stat(contextPath);
-      const dirPath = path.join(projectPath, dir);
-      const latestTsMtime = await getLatestTsMtime(dirPath);
-      if (latestTsMtime && latestTsMtime > contextStat.mtimeMs) {
-        result.contextStale.push(dir);
+      const contextMd = await fs.readFile(contextPath, 'utf-8');
+      const { surface, barrelExports } = await collectContextExportSurface(
+        path.join(projectPath, dir),
+        projectPath
+      );
+      const verdict = reconcileContext({
+        contextMdContent: contextMd,
+        exportSurface: surface,
+        barrelExports,
+      });
+      if (verdict.ghosts.length > 0 || verdict.unlistedBarrelExports.length > 0) {
+        result.contextContentDrift.push({
+          dir,
+          ghosts: verdict.ghosts,
+          unlisted: verdict.unlistedBarrelExports,
+        });
+      }
+
+      if (!isCi) {
+        const contextStat = await fs.stat(contextPath);
+        const latestTsMtime = await getLatestTsMtime(path.join(projectPath, dir));
+        if (latestTsMtime && latestTsMtime > contextStat.mtimeMs) {
+          result.contextStale.push(dir);
+        }
       }
     } catch {
       // 目录不存在或无法访问，跳过
@@ -231,8 +266,14 @@ export async function syncDocs(
 
   const hasTableIssues = result.added.length > 0 || result.removed.length > 0;
   const hasCapIssues = capCountMismatches.length > 0;
-  const hasContextIssues = result.contextMissing.length > 0 || result.contextStale.length > 0;
+  // mtime 只作提示，不参与判定（harness#142）：判定面是内容漂移与缺失
+  const hasContextIssues = result.contextMissing.length > 0 || result.contextContentDrift.length > 0;
   const hasIssues = hasTableIssues || hasCapIssues || hasContextIssues || hasAgentsIssues;
+  const contextDriftReason = result.contextContentDrift
+    .map((d) =>
+      `${d.dir}/CONTEXT.md（幽灵符号: ${d.ghosts.join(', ') || '无'}；` +
+      `barrel 未登记: ${d.unlisted.join(', ') || '无'}）`)
+    .join('、');
 
   // 5. JSON 输出模式：结构化输出供 LLM 消费
   if (isJson) {
@@ -245,6 +286,7 @@ export async function syncDocs(
         capCountMismatches: capCountMismatches.length,
         contextMissing: result.contextMissing.length,
         contextStale: result.contextStale.length,
+        contextContentDrift: result.contextContentDrift.length,
       },
       contextMissing: result.contextMissing.map(d => ({
         dir: d,
@@ -254,6 +296,12 @@ export async function syncDocs(
         dir: d,
         file: `${d}/CONTEXT.md`,
       })),
+      contentDrift: result.contextContentDrift.map((d) => ({
+        dir: d.dir,
+        file: `${d.dir}/CONTEXT.md`,
+        ghosts: d.ghosts,
+        unlisted: d.unlisted,
+      })),
       resolution: [] as Array<Record<string, unknown>>,
     };
 
@@ -298,6 +346,15 @@ export async function syncDocs(
         ...(result.contextMissing.length > 0
           ? [{ action: 'create-context-md', command: 'harness sync-docs', dirs: result.contextMissing }]
           : []),
+        ...(result.contextContentDrift.length > 0
+          ? [{
+              action: 'fix-context-content-drift',
+              details:
+                'CONTEXT.md「核心导出」节与目录导出面不一致：要么按实现改文档，要么在票面记录'
+                + '「文档正确、代码待改」；散文不可机械生成，sync-docs 不改写 CONTEXT.md',
+              drift: result.contextContentDrift,
+            }]
+          : []),
         ...(result.contextStale.length > 0
           ? [{ action: 'update-context-md', command: 'harness sync-docs', dirs: result.contextStale }]
           : []),
@@ -348,8 +405,22 @@ export async function syncDocs(
     result.contextMissing.forEach(d => log(io, chalk.gray(`  - ${d}/CONTEXT.md`)));
   }
 
+  if (result.contextContentDrift.length > 0) {
+    log(io, chalk.yellow(`\n📋 CONTEXT.md 与实现漂移（「核心导出」节 vs 目录导出面）:`));
+    result.contextContentDrift.forEach((d) => {
+      log(io, chalk.gray(`  - ${d.dir}/CONTEXT.md`));
+      if (d.ghosts.length > 0) {
+        log(io, chalk.gray(`      幽灵符号（文档声明、导出面已无）: ${d.ghosts.join(', ')}`));
+      }
+      if (d.unlisted.length > 0) {
+        log(io, chalk.gray(`      barrel 未登记（公开值符号未进「核心导出」节）: ${d.unlisted.join(', ')}`));
+      }
+    });
+    log(io, chalk.gray('  散文不可机械生成：按实现改文档，或在票面记录「文档正确、代码待改」'));
+  }
+
   if (result.contextStale.length > 0) {
-    log(io, chalk.yellow(`\n📋 CONTEXT.md 可能过时（源码比文档新）:`));
+    log(io, chalk.gray(`\n💡 提示：以下 CONTEXT.md 的源码比文档新（仅提示，不判失败）:`));
     result.contextStale.forEach(d => log(io, chalk.gray(`  - ${d}/CONTEXT.md`)));
   }
 
@@ -378,7 +449,12 @@ export async function syncDocs(
   // 7. 检查模式：只报告，不修改
   if (isCheck) {
     log(io, chalk.red('\n❌ 文档不是最新的，请运行 harness sync-docs 更新'));
-    return drift('文档不是最新的，请运行 harness sync-docs 更新');
+    // reason 必须可定位（harness#142）：CI 判红时要直接拿到文件与符号，不靠翻 stdout
+    return drift(
+      contextDriftReason
+        ? `文档不是最新的（CONTEXT.md 与实现漂移：${contextDriftReason}）`
+        : '文档不是最新的，请运行 harness sync-docs 更新'
+    );
   }
 
   // 8. 写入模式：更新文档
@@ -394,8 +470,7 @@ export async function syncDocs(
   }
 
   for (const dir of result.contextMissing) {
-    await createContextMd(projectPath, dir);
-    log(io, chalk.green(`✅ 已创建 ${dir}/CONTEXT.md`));
+    await createContextMd(projectPath, dir, io);
   }
 
   if (hasAgentsIssues && agentsMdExpected !== null) {

package/src/cli/commands/sync-docs/project-reader.ts

@@ -15,11 +15,28 @@ export interface ModuleInfo {
   description: string;
 }
 
+/** 描述提取的并发上限（#147 固定缺省，按票下裁决不做成配置面） */
+const DESCRIPTION_CONCURRENCY = 16;
+
+/**
+ * CONTEXT.md「核心导出」节与目录导出面的内容漂移（harness#142 / ADR-0025）。
+ * 两清单任一非空即漂移；判定本体在 core/constraints/context-reconcile。
+ */
+export interface ContextContentDrift {
+  dir: string;
+  /** 幽灵：文档声明、导出面已无 */
+  ghosts: string[];
+  /** 未登记：barrel 公开值符号未进「核心导出」节 */
+  unlisted: string[];
+}
+
 export interface SyncResult {
   added: string[];
   removed: string[];
   contextMissing: string[];
+  /** mtime 提示（源码比文档新）：不参与判定，只在本地给提示 */
   contextStale: string[];
+  contextContentDrift: ContextContentDrift[];
 }
 
 export interface PackageJsonLite {
@@ -94,10 +111,13 @@ export async function getSourceDirs(projectPath: string): Promise<string[]> {
 }
 
 /**
- * 扫描源码目录，提取模块信息
+ * 扫描源码目录，提取模块信息（harness#147：路径与描述分两步取）
+ *
+ * 第一步定清单（目录遍历序，逐字保持改造前口径），第二步并发取描述并按**原索引**回填
+ * ——清单顺序是对外可见面（`--check` 逐行比对生成的表格），不随读取完成先后漂移。
  */
 export async function scanSourceModules(srcDir: string, projectPath: string): Promise<ModuleInfo[]> {
-  const modules: ModuleInfo[] = [];
+  const found: { absPath: string; name: string; file: string }[] = [];
 
   let entries: string[];
   try {
@@ -119,22 +139,46 @@ export async function scanSourceModules(srcDir: string, projectPath: string): Pr
       // 与 .ts 同口径属预期，一次性补登记即可）
       const subFiles = findTsSourceFiles(entryPath, { skipIndex: true, includeTsx: true });
       for (const f of subFiles) {
-        modules.push({
+        found.push({
+          absPath: f,
           name: path.basename(f, path.extname(f)),
           file: path.relative(projectPath, f),
-          description: await extractFileDescription(f),
         });
       }
     } else if (isTsSourceFile(entry, { skipIndex: true, includeTsx: true })) {
-      modules.push({
+      found.push({
+        absPath: entryPath,
         name: path.basename(entry, path.extname(entry)),
         file: path.relative(projectPath, entryPath),
-        description: await extractFileDescription(entryPath),
       });
     }
   }
 
-  return modules;
+  const descriptions = await extractFileDescriptions(found.map((m) => m.absPath));
+  return found.map((m, i) => ({ name: m.name, file: m.file, description: descriptions[i] }));
+}
+
+/**
+ * 批量提取首行注释描述：并发取数、按索引回填（harness#147）
+ *
+ * 返回数组与入参同序同长，故调用方拿到的是「问哪份文件答哪份文件」。
+ * 上限是固定缺省（不是配置面）：描述提取是几百次小文件读，再放大并发只会压线程池。
+ */
+export async function extractFileDescriptions(filePaths: string[]): Promise<string[]> {
+  const descriptions = new Array<string>(filePaths.length);
+  let cursor = 0;
+
+  async function worker(): Promise<void> {
+    while (cursor < filePaths.length) {
+      const index = cursor++;
+      descriptions[index] = await extractFileDescription(filePaths[index]);
+    }
+  }
+
+  const workers = Math.min(DESCRIPTION_CONCURRENCY, filePaths.length);
+  await Promise.all(Array.from({ length: workers }, () => worker()));
+
+  return descriptions;
 }
 
 /**

package/src/cli/commands/validate.ts

@@ -11,6 +11,7 @@ import * as yaml from 'js-yaml';
 import { CheckpointValidator } from '../../core/validators/checkpoint';
 import type { Checkpoint, CheckpointContext } from '../../types/checkpoint';
 import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { DEFAULT_CHECKPOINT_FILE } from './scaffold-templates';
 
 export interface ValidateOptions {
   /** 检查点文件路径 */
@@ -21,11 +22,6 @@ export interface ValidateOptions {
   strict?: boolean;
 }
 
-/**
- * 默认检查点文件路径
- */
-const DEFAULT_CHECKPOINT_FILE = '.harness/checkpoints.yml';
-
 /**
  * 加载检查点配置
  */
@@ -107,102 +103,3 @@ export async function validate(
   log(io, chalk.green('\n✅ 所有检查点验证通过'));
   return { kind: 'ok' };
 }
-
-/**
- * 默认检查点列表（供 init 和 upgrade 共用）
- *
- * 注：no-console 检查点已移除（工单 23/24）——CLI 产品 src/ 必然有合法 console 输出，
- * 且旧配置 expected:'' 语义恒错；output_* 族修复为真正执行 config.command 后该检查会恒失败。
- */
-export const DEFAULT_CHECKPOINTS: Checkpoint[] = [
-  {
-    id: 'build-success',
-    name: '构建成功',
-    checks: [
-      {
-        id: 'build-command',
-        type: 'command_success',
-        config: { command: 'npm run build' },
-        message: '构建命令必须成功执行',
-      },
-    ],
-  },
-  {
-    id: 'test-pass',
-    name: '测试通过',
-    checks: [
-      {
-        id: 'test-command',
-        type: 'command_success',
-        config: { command: 'npm test' },
-        message: '测试命令必须成功执行',
-      },
-    ],
-  },
-];
-
-/**
- * 创建示例检查点文件
- */
-export async function createExampleCheckpoint(projectPath: string, io: CommandIO = processIO): Promise<void> {
-  const filePath = path.join(projectPath, DEFAULT_CHECKPOINT_FILE);
-  const dir = path.dirname(filePath);
-
-  // 如果已存在，不覆盖
-  try {
-    await fs.access(filePath);
-    log(io, chalk.gray(`checkpoints.yml 已存在，跳过`));
-    return;
-  } catch {
-    // 文件不存在，创建
-  }
-
-  await fs.mkdir(dir, { recursive: true });
-
-  const content = yaml.dump({ checkpoints: DEFAULT_CHECKPOINTS }, { indent: 2 });
-  await fs.writeFile(filePath, content, 'utf-8');
-
-  log(io, chalk.green(`✅ 已创建示例检查点文件: ${filePath}`));
-}
-
-/**
- * 默认 Resolutions（RKB — 约束 → 已知解法映射）
- */
-const DEFAULT_RESOLUTIONS = {
-  no_fuzzy_completion_claim: {
-    title: 'commit message 缺少验证证据',
-    fix: '在 commit message body 中附上验证输出:\n`npx @dommaker/harness check --staged` | `npx @dommaker/harness validate` | `npm test -- --coverage`\n确认全部通过后重新 commit。',
-  },
-  capability_sync: {
-    title: '缺少 CAPABILITIES.md',
-    fix: '在项目根目录创建 CAPABILITIES.md，列出所有模块能力清单。运行 `npx @dommaker/harness sync-docs` 可自动生成模板。',
-  },
-  context_doc_sync: {
-    title: '关键目录缺少 CONTEXT.md',
-    fix: '在 required_dirs 目录下创建 CONTEXT.md。运行 `npx @dommaker/harness sync-docs` 可自动生成模板。',
-  },
-};
-
-/**
- * 创建示例 Resolutions 文件（RKB dogfood）
- */
-export async function createExampleResolutions(projectPath: string, io: CommandIO = processIO): Promise<void> {
-  const harnessDir = path.join(projectPath, '.harness');
-  const filePath = path.join(harnessDir, 'resolutions.json');
-
-  // 如果已存在，不覆盖
-  try {
-    await fs.access(filePath);
-    log(io, chalk.gray(`resolutions.json 已存在，跳过`));
-    return;
-  } catch {
-    // 文件不存在，创建
-  }
-
-  await fs.mkdir(harnessDir, { recursive: true });
-
-  const content = JSON.stringify(DEFAULT_RESOLUTIONS, null, 2);
-  await fs.writeFile(filePath, content, 'utf-8');
-
-  log(io, chalk.green(`✅ 已创建 Resolutions 文件: ${filePath}`));
-}

package/src/cli/gate-command.ts

@@ -0,0 +1,87 @@
+/**
+ * 门禁命令共享面（架构评审候选1）
+ *
+ * 六个门禁命令原先各写一遍「报告 → 成败」的翻译与 ✓/✗ 输出，同一句话抄 6 处。
+ * 这里只留一份：`GateDecision → CommandResult` 的唯一映射，加人类视图骨架。
+ *
+ * `command` 门禁的输出是单行机器友好形态（自带 ✓/✗ 与 --json），只复用映射、
+ * 不套骨架——套的话等于逼它换掉已对外的输出形状。
+ */
+
+import chalk from 'chalk';
+import type { GateDecision, GateResult } from '../gates/types';
+import { log, type CommandIO, type CommandResult } from './command-contract';
+
+/**
+ * 门禁命令的人类视图
+ */
+export interface GateCommandView {
+  /** 门禁 id（与注册表一致），决定失败 reason 的前缀 */
+  gateId: string;
+  /** 横幅用词，如「代码审查门控」「验收标准」 */
+  label: string;
+  /** 通过时追加的指标行（自行上色，空串表示空行） */
+  onPass?: (result: GateResult) => string[];
+  /** 未通过时在原因行之后追加的详情行 */
+  onFail?: (result: GateResult) => string[];
+}
+
+/**
+ * 决策 → 命令结果：六个门禁唯一一处映射
+ */
+export function gateCommandResult(gateId: string, decision: GateDecision): CommandResult {
+  if (decision.status === 'abstain') {
+    return { kind: 'ok' };
+  }
+  // ask 无实现者，按拦下计——与 runGates 的 fail-closed 聚合同一条规则
+  return { kind: 'fail', reason: `${gateId} gate denied: ${decision.result.message}` };
+}
+
+/**
+ * 打印决策并给出命令结果
+ */
+export function reportGateDecision(
+  io: CommandIO,
+  view: GateCommandView,
+  decision: GateDecision
+): CommandResult {
+  const result = decision.result;
+  log(io);
+
+  if (decision.status === 'abstain') {
+    log(io, chalk.green(`✅ ${view.label}检查通过`));
+    for (const line of view.onPass?.(result) ?? []) {
+      log(io, line);
+    }
+  } else {
+    log(io, chalk.red(`❌ ${view.label}检查失败`));
+    log(io, chalk.red(`   ${result.message}`));
+    for (const line of view.onFail?.(result) ?? []) {
+      log(io, line);
+    }
+  }
+
+  return gateCommandResult(view.gateId, decision);
+}
+
+/**
+ * 门禁自身之外的抛出物（git / fs）→ 出错横幅 + fail
+ */
+export function reportGateError(
+  io: CommandIO,
+  gateId: string,
+  label: string,
+  error: unknown,
+  extra?: (message: string) => string[]
+): CommandResult {
+  const message = error instanceof Error ? error.message : String(error);
+
+  log(io);
+  log(io, chalk.red(`❌ ${label}检查出错`));
+  log(io, chalk.red(`   ${message}`));
+  for (const line of extra?.(message) ?? []) {
+    log(io, line);
+  }
+
+  return { kind: 'fail', reason: `${gateId} gate error: ${message}` };
+}

package/src/completion-checkers/index.ts

@@ -10,7 +10,16 @@
  * 函数不碰文件系统与 git；commits 由调用方（completion-gates 类守卫）供给。
  */
 
-export * from './types';
+export type {
+  CommitInput,
+  CheckerVerdict,
+  CommitVerdict,
+  TddChainResult,
+  PhaseFormatResult,
+  ContractPresenceContext,
+  ContractPresenceResult,
+  CompletionCheckersConfig,
+} from './types';
 export { DEFAULT_TEST_GLOBS, DEFAULT_NONCODE_GLOBS, matchGlob, matchAnyGlob } from './glob-match';
 export { classifyCommitFiles, resolveGlobs } from './classify';
 export type { CommitFileClassification } from './classify';

package/src/context/CONTEXT.md

@@ -5,8 +5,9 @@
 
 ## 核心导出
 - `TokenBudget` — 多级 token 预算(system/user/tool/reserve)
+- `TokenEstimator` — 快速 token 估算静态类（`estimateText`：英文按 1 token≈4 字符、中文≈1.5 字符，非精确 tokenizer；仓内消费方是 `KnowledgeInjector` 的截断取数）
 - `SessionManager` — 会话管理
-- `KnowledgeInjector` — 知识注入引擎
+- `KnowledgeInjector` — 知识注入引擎；`origin === 'external'` 条目注入时带 `[External Source — verify before acting]` 前缀（标记唯一正本是 `knowledge/query.ts` 的 `EXTERNAL_SOURCE_MARKER`，本目录不另存字面量），注入 source 的 metadata 带 `entryId`/`maturity`/`origin`（外部内容三层防御第二层，harness#161）
 
 ## 依赖关系
 - 依赖 `src/types/` 公共类型

package/src/context/__tests__/knowledge-injector.test.ts

@@ -143,6 +143,33 @@ describe('KnowledgeInjector', () => {
     });
   });
 
+  describe('外部内容 retrieval marking（harness#161 三层防御第二层接线）', () => {
+    it('origin: external 条目注入时 prompt 带来源标记，metadata 含 origin', () => {
+      saveEntry({ id: 'ext-1', title: 'External Tip', origin: 'external' });
+      const result = injector.inject({ budget: 8000 });
+      expect(result.sources).toHaveLength(1);
+      expect(result.sources[0].content).toContain('[External Source — verify before acting]');
+      expect(result.sources[0].metadata).toMatchObject({ entryId: 'ext-1', origin: 'external' });
+    });
+
+    it('非 external 条目不带来源标记，metadata 仍带 origin', () => {
+      saveEntry({ id: 'int-1', title: 'Internal', origin: 'agent' });
+      const result = injector.inject({ budget: 8000 });
+      expect(result.sources).toHaveLength(1);
+      expect(result.sources[0].content).not.toContain('[External Source — verify before acting]');
+      expect(result.sources[0].metadata).toMatchObject({ origin: 'agent' });
+    });
+
+    it('external 条目的摘要注入同样带来源标记与 origin metadata', () => {
+      saveEntry({ id: 'ext-2', title: 'Ext', origin: 'external' });
+      const result = injector.inject({ budget: 8000, exclude: ['ext-2'] });
+      const summary = result.sources.find(s => s.id === 'knowledge-summary-ext-2');
+      expect(summary).toBeDefined();
+      expect(summary!.content).toContain('[External Source — verify before acting]');
+      expect(summary!.metadata).toMatchObject({ origin: 'external' });
+    });
+  });
+
   describe('getQuery', () => {
     it('应该返回查询引擎', () => {
       expect(injector.getQuery()).toBe(query);

package/src/context/__tests__/session-manager.test.ts

@@ -5,18 +5,25 @@
 import { SessionManager } from '../session-manager';
 import * as fs from 'fs';
 
-jest.mock('fs', () => ({
-  mkdirSync: jest.fn(),
-  appendFileSync: jest.fn(),
-  existsSync: jest.fn().mockReturnValue(false),
-  readFileSync: jest.fn().mockReturnValue(''),
-  readdirSync: jest.fn().mockReturnValue([]),
-  writeFileSync: jest.fn(),
-  statSync: jest.fn().mockReturnValue({
-    birthtime: new Date(),
-    mtime: new Date(),
-  }),
-}));
+jest.mock('fs', () => {
+  // restoreSession 经有界 head 读 events.jsonl（ADR-0023 决策 3），需要倒读四件；
+  // 内容仍由下面按路径分派的 readFileSync 提供，两条读入口同源（夹具说明见其文件头）
+  const { jsonlBoundedReadChain } = require('../../test-setup/jsonl-fake-fs');
+  const readFileSync = jest.fn().mockReturnValue('');
+  return {
+    mkdirSync: jest.fn(),
+    appendFileSync: jest.fn(),
+    existsSync: jest.fn().mockReturnValue(false),
+    readFileSync,
+    readdirSync: jest.fn().mockReturnValue([]),
+    writeFileSync: jest.fn(),
+    statSync: jest.fn().mockReturnValue({
+      birthtime: new Date(),
+      mtime: new Date(),
+    }),
+    ...jsonlBoundedReadChain((p: string) => readFileSync(p, 'utf-8')),
+  };
+});
 
 const mockFs = fs as jest.Mocked<typeof fs>;