@danceiny/gotry 0.0.1-rc.8 → 0.2.0-rc.27

package/dist/scripts/itinerary-deck-artifact-tests.js

@@ -0,0 +1,416 @@
+/**
+ * 行程 deck 产物生成入口的注册工具 E2E(issue #566,Phase B 切片 2;
+ * 与 issue #442 单页入口镜像)。
+ *
+ * 真实执行面:在隔离临时 stateRoot 下 `apply(ctx, config)` 装载 gotry-tools 插件,
+ * 取**注册定义** `gotry_itinerary_deck_render` 的 execute 直调(与本仓库既有
+ * registered-e2e 同构),exec 上下文给出真实会话 cwd。事实经 `appendFacts` 写入
+ * 隔离注册表(<stateRoot>/gotry-state/bookable-facts.jsonl),生成入口只能从那里取。
+ *
+ * 覆盖(对照单页 itinerary-artifact-tests.ts 同一份验收面;deck 差异在 §3/§4
+ * 增补的形态契约:scroll-snap 零脚本翻页 / 11 张幻灯确定性派生 / 命名契约前缀):
+ *   1. 空 fact_ids = 明确未核验计划:落盘成功、无整体「已验证」徽章、无写入 stateRoot;
+ *   2. 选中 3 条事实:落盘字节 == 同输入 deck 渲染器输出(事实顺序/内容均由注册表决定);
+ *   3. 未知 id / 重复 id / 超量 id 一律拒绝且零写入;
+ *   4. 登记行畸形 → 渲染器显式拒绝,零写入;
+ *   5. 调用方自带 facts 对象不被接受(空列表不投影、伪造 id 走未知 id 拒绝);
+ *   6. 显式 basename 撞车不覆盖(字节不变);
+ *   7. 符号链接目标不被改写(排除链接逃逸);
+ *   8. basename 路径分隔符 / 越级 / 错误前缀 / 超长 / 绝对路径全部拒绝,仓外零文件;
+ *   9. 会话 cwd 位于 .git/node_modules 段或不存在 → 拒绝;
+ *  10. 随机默认名符合 `gotry-deck-` 契约且两次不同;同一输入两次生成字节一致(确定性);
+ *  11. 畸形 title/itinerary/fact_ids 类型 → 拒绝且零写入;
+ *  12. 缺失/空对象/空串/纯空白/非字符串/相对的会话 cwd → 工具层与能力层都 fail closed,
+ *      进程 cwd 零新增文件(绝不回落 process.cwd());
+ *  13. 真实产出链路(注册工具):生成 → gotry_artifacts_list 在册同一路径 → gotry_artifacts_read
+ *      以 html 源码文本读回,内容与落盘字节逐字一致、version 与磁盘 sha256 一致;
+ *  14. 路径保真:宿主 cwd 的尾随空格属于路径本身——同时存在 `session` 与 `session ` 时,
+ *      工具层与能力层都只写进宿主给出的那一个,绝不 trim 归一化到同名兄弟目录;
+ *      只有兄弟存在时带空格路径按不存在拒绝;
+ *  15. deck 形态契约:零脚本 / 无远端依赖 / 纯 CSS scroll-snap 翻页 / 11 张幻灯确定性派生 /
+ *      共享 evidence 边界声明。
+ * 全部合成事实,无用户真实行程;不启动 dsh 宿主、无网络、无供应商调用。
+ *
+ * 运行(在 ts/ 下):
+ *   PATH=/opt/homebrew/opt/node@24/bin:$PATH npx tsx scripts/itinerary-deck-artifact-tests.ts
+ */
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, lstatSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { apply } from '../src/index.js';
+import { BOOKABLE_FACT_SCHEMA, } from '../src/bookable-facts.js';
+import { appendFacts, loadFactRegistry } from '../capabilities/fact-log.js';
+import { generateItineraryDeckArtifact } from '../capabilities/itinerary-deck-artifact.js';
+import { renderItineraryDeck } from '../src/itinerary-deck.js';
+import { ITINERARY_DECK_ARTIFACT_BASENAME_RE } from '../capabilities/itinerary-deck-artifact.js';
+let pass = 0;
+let fail = 0;
+const failures = [];
+function ok(cond, msg) {
+    if (cond) {
+        pass++;
+        return;
+    }
+    fail++;
+    failures.push(msg);
+}
+const TITLE = '合成行程:深圳 → 普吉(内部切片夹具)';
+const ITINERARY = {
+    trip_start: '2027-07-16',
+    trip_end: '2027-07-24',
+    stays: [
+        { place: '普吉岛', check_in: '2027-07-17', check_out: '2027-07-21' },
+        { place: '甲米', check_in: '2027-07-21', check_out: '2027-07-23' },
+    ],
+    od_segments: [
+        { from: '广州南', to: '深圳北', date: '2027-07-16', mode: 'rail', legs: 1 },
+        { from: 'SZX', to: 'HKT', date: '2027-07-17', mode: 'flight', legs: 1 },
+        { from: 'HKT', to: 'BKK', date: '2027-07-21', mode: 'flight', legs: 2 },
+    ],
+};
+const FLIGHT_ID = 'i566flight0001';
+const HOTEL_ID = 'i566hotel0001';
+const POLICY_ID = 'i566policy0001';
+const TRAIN_ID = 'i566train00001';
+const FLIGHT = {
+    schema: BOOKABLE_FACT_SCHEMA,
+    fact_id: FLIGHT_ID,
+    kind: 'flight',
+    route: { origin: 'SZX', destination: 'HKT', origin_airport: 'SZX', dest_airport: 'HKT' },
+    date: '2027-07-17',
+    flight_no: 'CZ6061',
+    marketing_carrier: '南方航空',
+    dep_local: '09:20',
+    arr_local: '12:05',
+    nonstop: true,
+    price: 1680,
+    currency: 'CNY',
+    tier: 'live_inventory',
+    bookability: 'bookable_exact_date',
+    source: 'session:ctrip-flight',
+    query_id: 'session:ctrip-flight:flight:SZX-HKT:2027-07-17',
+    fetched_at: '2026-09-12T02:10:03.000Z',
+    as_of: '2026-09-12',
+};
+const TRAIN = {
+    schema: BOOKABLE_FACT_SCHEMA,
+    fact_id: TRAIN_ID,
+    kind: 'train',
+    route: { origin: '广州南', destination: '深圳北' },
+    date: '2027-07-16',
+    flight_no: 'G6011',
+    dep_local: '07:12',
+    arr_local: '07:48',
+    tier: 'historical_schedule',
+    bookability: 'unverified',
+    source: 'flyai',
+    query_id: 'flyai:train:广州南-深圳北:2027-07-16',
+    fetched_at: '2026-09-12T02:00:00.000Z',
+    as_of: '2026-08-01',
+};
+const HOTEL = {
+    schema: BOOKABLE_FACT_SCHEMA,
+    fact_id: HOTEL_ID,
+    kind: 'hotel',
+    destination: '普吉岛',
+    check_in: '2027-07-17',
+    check_out: '2027-07-21',
+    verdict: 'hit',
+    bookability: 'bookable_exact_date',
+    options_masked: 37,
+    source: 'flyai-hotel',
+    query_id: 'hotel:flyai-hotel:普吉岛:2027-07-17_2027-07-21',
+    fetched_at: '2026-09-12T02:20:00.000Z',
+    as_of: '2026-09-12',
+    tier: 'live_inventory',
+};
+const POLICY = {
+    schema: BOOKABLE_FACT_SCHEMA,
+    fact_id: POLICY_ID,
+    kind: 'policy',
+    subject: '泰国免签',
+    statement: '中国护照可免签入境停留不超过 30 天(以落地执行口径为准)',
+    source: 'flyai',
+    query_id: 'flyai:policy:泰国免签',
+    fetched_at: '2026-09-12T02:30:00.000Z',
+    as_of: '2026-09-12',
+    review_by: '2027-06-17',
+};
+function loadTools(stateRoot) {
+    assert.ok(stateRoot.startsWith(tmpdir()), 'stateRoot 必须是隔离临时根(绝不触真实 stateRoot)');
+    const registered = [];
+    const ctx = {
+        tools: { register: (t) => { registered.push(t); } },
+        systemPrompt: { variable: () => { } },
+        on: () => () => { },
+    };
+    apply(ctx, { stateRoot, timeoutMs: 30_000, hbcliBin: 'hbcli-not-on-path', sessionAccess: 'ask' });
+    return new Map(registered.map(t => [t.name, t]));
+}
+function htmlFiles(dir) {
+    return readdirSync(dir).filter(n => n.endsWith('.html')).sort();
+}
+function deckFiles(dir) {
+    return readdirSync(dir).filter(n => n.startsWith('gotry-deck-') && n.endsWith('.html')).sort();
+}
+function renderDeck(facts) {
+    const r = renderItineraryDeck({ title: TITLE, itinerary: ITINERARY, facts });
+    assert.ok(r.ok, `对照渲染必须成功:${r.ok ? '' : JSON.stringify(r.errors)}`);
+    return r.ok ? r.html : '';
+}
+function countOf(haystack, needle) {
+    return haystack.split(needle).length - 1;
+}
+async function main() {
+    const home = mkdtempSync(join(tmpdir(), 'gotry-566-artifact-'));
+    const stateRoot = join(home, 'state');
+    const cwd = join(home, 'workspace');
+    const outside = join(home, 'outside');
+    for (const d of [stateRoot, cwd, outside])
+        mkdirSync(d, { recursive: true });
+    const outsideFile = join(outside, 'target.html');
+    writeFileSync(outsideFile, 'DO NOT TOUCH', 'utf-8');
+    const tools = loadTools(stateRoot);
+    const tool = tools.get('gotry_itinerary_deck_render');
+    assert.ok(tool, 'gotry_itinerary_deck_render 必须已注册');
+    // deck 工具与单页工具并存:注册定义同名检查
+    ok(Boolean(tools.get('gotry_itinerary_render')), '§0a 单页入口(issue #442)仍注册');
+    if (!tool) {
+        console.log('\nITINERARY DECK ARTIFACT TESTS: 0 pass, 1 fail');
+        console.log('  - 工具未注册');
+        process.exit(1);
+    }
+    const exec = { agent: { session: { header: { cwd } } } };
+    const run = async (args, execCtx = exec) => await tool.execute(args, execCtx);
+    // ---- §1 模型可见契约(fact_ids 必填、空数组合法) ----
+    const params = tool.parameters;
+    ok(params.required?.includes('fact_ids') === true, '§1a fact_ids 是必填参数');
+    ok(params.properties?.fact_ids?.type === 'array' && params.properties?.fact_ids?.items?.type === 'string', '§1b fact_ids 是字符串数组参数');
+    ok(params.required?.includes('title') === true, '§1c title 必填');
+    ok(params.required?.includes('itinerary') === true, '§1d itinerary 必填');
+    ok(params.required?.includes('basename') !== true, '§1e basename 可选');
+    ok(/registry/i.test(tool.description), '§1f 描述声明事实只从注册表取');
+    ok(/never overwrites/i.test(tool.description), '§1g 描述声明绝不覆盖');
+    ok(/DECK|deck/i.test(tool.description), '§1h 描述声明 deck 形态');
+    ok(/gotry-deck-/.test(tool.description), '§1i 描述声明 deck 命名前缀');
+    // ---- §2 事实登记进隔离注册表 ----
+    ok(await appendFacts(stateRoot, [FLIGHT, TRAIN, HOTEL, POLICY]), '§2a 合成事实写入隔离注册表');
+    const registry = await loadFactRegistry(stateRoot);
+    ok(registry.length === 4, `§2b 注册表读回 4 条(实测 ${registry.length})`);
+    ok(deckFiles(cwd).length === 0, '§2c 生成前工作目录无 deck html');
+    // ---- §3 空 fact_ids = 明确未核验计划 + deck 形态契约 ----
+    const empty = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [] });
+    ok(empty.ok === true, `§3a 空 fact_ids 合法(实际:${JSON.stringify(empty.error ?? '')})`);
+    ok(empty.overall_verified === false, '§3b 结果显式声明无整体「已验证」结论');
+    ok(deckFiles(cwd).length === 1, `§3c 落盘 1 个 deck html(实测 ${deckFiles(cwd).length})`);
+    const emptyPath = String(empty.path ?? '');
+    ok(emptyPath.endsWith(String(empty.basename)), '§3d 返回最终真实路径');
+    const emptyDisk = readFileSync(emptyPath, 'utf-8');
+    ok(emptyDisk === renderDeck([]), '§3e 落盘字节 == 同输入 deck 渲染器输出');
+    ok(empty.bytes === Buffer.byteLength(emptyDisk, 'utf8'), '§3f bytes 与磁盘字节一致');
+    ok(emptyDisk.split('class="badge ok"').length - 1 === 0, '§3g 空事实文档没有任何 ok 徽章');
+    ok(emptyDisk.includes('共 0 条事实'), '§3h 文档显式陈述 0 条事实');
+    ok(emptyDisk.includes('该段没有匹配的已注册事实'), '§3i 计划段显式标注未核验');
+    ok(!emptyDisk.includes('<script'), '§3j 产物无 script(零脚本翻页)');
+    ok(!emptyDisk.includes('http://') && !emptyDisk.includes('https://'), '§3k 产物无远端资源');
+    // deck 形态契约(issue #564):纯 CSS scroll-snap / 11 张幻灯 / 共享 evidence 边界
+    ok(emptyDisk.includes('html{scroll-snap-type:y proximity}') && emptyDisk.includes('scroll-snap-align:start'), '§3l 纯 CSS scroll-snap 翻页');
+    // 空事实输入:政策幻灯(仅当有政策事实时存在)被跳过,余 10 张
+    ok(countOf(emptyDisk, '<section class="slide') === 10, `§3m 空事实输入 10 张幻灯确定性派生(实测 ${countOf(emptyDisk, '<section class="slide')})`);
+    ok(emptyDisk.includes('本文档只投影调用方给出的显式行程与已注册事实'), '§3n 共享 evidence 边界声明(单面文案逐字一致)');
+    ok(readdirSync(stateRoot).filter(n => n.endsWith('.html')).length === 0, '§3o stateRoot 下不写 html(只写会话工作目录)');
+    // ---- §4 选中注册表事实:字节与 deck 渲染器一致,按调用方顺序选中 ----
+    const selected = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [FLIGHT_ID, HOTEL_ID, POLICY_ID] });
+    ok(selected.ok === true, `§4a 已注册 id 选中成功(实际:${JSON.stringify(selected.error ?? '')})`);
+    const selectedDisk = readFileSync(String(selected.path), 'utf-8');
+    ok(selectedDisk === renderDeck([FLIGHT, HOTEL, POLICY]), '§4b 落盘字节 == 注册表选出的 3 条事实的 deck 输出');
+    ok(selectedDisk.split('class="badge ok"').length - 1 > 0, '§4c 逐条事实带可下单徽章(非整体徽章)');
+    for (const id of [FLIGHT_ID, HOTEL_ID, POLICY_ID])
+        ok(selectedDisk.includes(id), `§4d 事实 ${id} 在产物中可见`);
+    ok(selectedDisk.includes('独立记录:目的地级酒店事实'), '§4e 酒店证据独立成区(不冒充某家酒店可订)');
+    ok(selectedDisk.includes('slide-hotel-evidence') && selectedDisk.includes('slide-policy') && selectedDisk.includes('slide-leftovers') && selectedDisk.includes('slide-flights'), '§4f deck 证据幻灯齐全');
+    ok(Array.isArray(selected.fact_ids) && selected.fact_ids.join(',') === [FLIGHT_ID, HOTEL_ID, POLICY_ID].join(','), '§4g 结果回显选中顺序');
+    const reversed = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [POLICY_ID, FLIGHT_ID, HOTEL_ID] });
+    ok(reversed.ok === true && reversed.bytes === selected.bytes, '§4h 顺序变化不改变 deck 文档字节(确定性投影)');
+    // ---- §5 未知 id 拒绝,零写入 ----
+    const before5 = deckFiles(cwd).length;
+    const unknown = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: ['i566notthere'] });
+    ok(unknown.ok === false && String(unknown.error).includes('i566notthere'), '§5a 未知 id 显式拒绝并回显 id');
+    ok(deckFiles(cwd).length === before5, '§5b 未知 id 零写入');
+    // ---- §6 重复 id 拒绝,零写入 ----
+    const dup = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [FLIGHT_ID, FLIGHT_ID] });
+    ok(dup.ok === false && /重复/.test(String(dup.error)), '§6a 重复 id 拒绝');
+    ok(deckFiles(cwd).length === before5, '§6b 重复 id 零写入');
+    // ---- §7 超量 id 拒绝,零写入 ----
+    const many = Array.from({ length: 201 }, (_, i) => `i566bulk${i}`);
+    const over = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: many });
+    ok(over.ok === false && /容量上限/.test(String(over.error)), '§7a 超量 id 拒绝');
+    ok(deckFiles(cwd).length === before5, '§7b 超量 id 零写入');
+    // ---- §8 登记行畸形 → deck 渲染器拒绝,零写入 ----
+    const malformed = { ...HOTEL, fact_id: 'i566malformed01', verdict: 'hit', options_masked: 'many' };
+    ok(await appendFacts(stateRoot, [malformed]), '§8a 畸形登记行写入注册表');
+    const malformedRun = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: ['i566malformed01'] });
+    ok(malformedRun.ok === false, '§8b 畸形登记行不渲染成功');
+    ok(Array.isArray(malformedRun.errors) && malformedRun.errors.length > 0, '§8c 畸形行给出结构化 errors(渲染器校验)');
+    ok(deckFiles(cwd).length === before5, '§8d 畸形行零写入');
+    // ---- §9 调用方自带 facts 不被接受 ----
+    const forgedId = 'i566forged0001';
+    const callerFacts = await run({
+        title: TITLE,
+        itinerary: ITINERARY,
+        fact_ids: [],
+        facts: [{ schema: BOOKABLE_FACT_SCHEMA, fact_id: forgedId, kind: 'flight' }],
+    });
+    ok(callerFacts.ok === true, '§9a 额外的 facts 字段不影响空列表生成');
+    ok(!readFileSync(String(callerFacts.path), 'utf-8').includes(forgedId), '§9b 调用方自带事实对象不被投影');
+    const forged = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [forgedId] });
+    ok(forged.ok === false, '§9c 伪造 id(只存在于调用方入参)按未知 id 拒绝');
+    ok(deckFiles(cwd).length === before5 + 1, '§9d 仅 §9a 新增一个文件');
+    // ---- §10 显式 basename 撞车不覆盖(deck 命名契约) ----
+    const named = 'gotry-deck-2027-phuket.html';
+    const first = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [FLIGHT_ID], basename: named });
+    ok(first.ok === true && first.basename === named, '§10a 合法 deck basename 生成成功');
+    const namedPath = join(cwd, named);
+    const namedBytes = readFileSync(namedPath, 'utf-8');
+    const second = await run({ title: '合成行程:第二次(不应覆盖)', itinerary: ITINERARY, fact_ids: [FLIGHT_ID], basename: named });
+    ok(second.ok === false && /拒绝覆盖/.test(String(second.error)), '§10b 同名第二次拒绝覆盖');
+    ok(readFileSync(namedPath, 'utf-8') === namedBytes, '§10c 既有产物字节未被改写');
+    // ---- §11 符号链接目标不被改写 ----
+    const linkName = 'gotry-deck-link.html';
+    symlinkSync(outsideFile, join(cwd, linkName));
+    const linked = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [FLIGHT_ID], basename: linkName });
+    ok(linked.ok === false, '§11a 指向别处的符号链接不被跟随写入');
+    ok(readFileSync(outsideFile, 'utf-8') === 'DO NOT TOUCH', '§11b 链接目标字节未被改写');
+    ok(lstatSync(join(cwd, linkName)).isSymbolicLink(), '§11c 链接本身未被替换');
+    // ---- §12 deck basename 路径与命名契约(前缀不同 + 与单页契约互不兼容) ----
+    const before12 = deckFiles(cwd).length;
+    const rejectNames = [
+        '../../evil.html',
+        'sub/evil.html',
+        'sub\\evil.html',
+        join(outside, 'evil.html'),
+        'evil.html',
+        'gotry-deck-.html',
+        'gotry-deck-2027-phuket.HTML',
+        `gotry-deck-${'a'.repeat(70)}.html`,
+        'gotry-deck-2027 phuket.html',
+        // 单页前缀不应被 deck 工具接受(契约互不兼容,避免文件名撞车归责混乱)
+        'gotry-itinerary-2027-phuket.html',
+    ];
+    for (const name of rejectNames) {
+        const r = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [], basename: name });
+        ok(r.ok === false, `§12a basename 拒绝:${name}`);
+    }
+    ok(deckFiles(cwd).length === before12, `§12b 拒绝的 basename 未产生 deck 文件(实测 ${deckFiles(cwd).length})`);
+    ok(!readdirSync(outside).includes('evil.html'), '§12c 仓外无越级文件');
+    // 单页契约仍由 gotry_itinerary_render 单独负责(两个工具并存、契约不互串)
+    ok(ITINERARY_DECK_ARTIFACT_BASENAME_RE.source.startsWith('^gotry-deck-'), '§12d 契约 regex 锁定 gotry-deck- 前缀');
+    // ---- §13 会话 cwd 边界 ----
+    for (const bad of [join(stateRoot, 'node_modules'), join(home, '.git'), join(home, 'nope')]) {
+        mkdirSync(join(stateRoot, 'node_modules'), { recursive: true });
+        mkdirSync(join(home, '.git'), { recursive: true });
+        const r = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [] }, { agent: { session: { header: { cwd: bad } } } });
+        ok(r.ok === false, `§13a 受限/不存在的 cwd 拒绝:${bad}`);
+    }
+    ok(readdirSync(join(home, '.git')).length === 0, '§13b .git 段零写入');
+    ok(readdirSync(join(stateRoot, 'node_modules')).length === 0, '§13c node_modules 段零写入');
+    // ---- §14 随机默认名 + 真实路径 ----
+    const r1 = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [] });
+    const r2 = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [] });
+    ok(r1.ok === true && r2.ok === true, '§14a 默认随机名连续生成成功');
+    ok(ITINERARY_DECK_ARTIFACT_BASENAME_RE.test(String(r1.basename)), '§14b 随机名符合 deck 命名契约');
+    ok(r1.basename !== r2.basename, '§14c 连续两次随机名不同');
+    ok(String(r1.path) === join(realpathSync(cwd), String(r1.basename)), '§14d 返回路径 = 会话工作目录(realpath)+ basename');
+    // ---- §15 畸形输入拒绝,零写入 ----
+    const before15 = deckFiles(cwd).length;
+    const invalid = [
+        { title: TITLE, itinerary: ITINERARY },
+        { title: TITLE, itinerary: ITINERARY, fact_ids: 'not-an-array' },
+        { title: TITLE, itinerary: ITINERARY, fact_ids: [42] },
+        { title: TITLE, itinerary: ITINERARY, fact_ids: [''] },
+        { itinerary: ITINERARY, fact_ids: [] },
+        { title: TITLE, fact_ids: [] },
+        { title: TITLE, itinerary: { ...ITINERARY, trip_start: '2027-02-30' }, fact_ids: [] },
+        { title: TITLE, itinerary: { ...ITINERARY, od_segments: [{ from: 'SZX', to: 'HKT', date: '2027-07-17', mode: 'teleport', legs: 1 }] }, fact_ids: [] },
+    ];
+    for (const [i, args] of invalid.entries()) {
+        const r = await run(args);
+        ok(r.ok === false, `§15a 畸形输入 ${i} 拒绝`);
+    }
+    ok(deckFiles(cwd).length === before15, `§15b 畸形输入零写入(实测 ${deckFiles(cwd).length})`);
+    // ---- §16 会话 cwd 非法一律 fail closed(零写入,绝不回落进程 cwd) ----
+    const procCwdBefore = readdirSync(process.cwd()).sort().join(',');
+    const badExecs = [
+        ['缺 exec', undefined],
+        ['空对象 exec', {}],
+        ['无 session', { agent: {} }],
+        ['无 header', { agent: { session: {} } }],
+        ['header 无 cwd', { agent: { session: { header: {} } } }],
+        ['cwd 空串', { agent: { session: { header: { cwd: '' } } } }],
+        ['cwd 纯空白', { agent: { session: { header: { cwd: '   ' } } } }],
+        ['cwd 非字符串', { agent: { session: { header: { cwd: 42 } } } }],
+        ['cwd 相对路径', { agent: { session: { header: { cwd: 'relative/workspace' } } } }],
+    ];
+    for (const [label, badExec] of badExecs) {
+        const r = await tool.execute({ title: TITLE, itinerary: ITINERARY, fact_ids: [] }, badExec);
+        ok(r.ok === false, `§16a 非法会话 cwd 拒绝:${label}`);
+        ok(/会话工作目录/.test(String(r.error)), `§16b 拒绝原因是会话工作目录缺失/非法:${label}`);
+    }
+    ok(readdirSync(process.cwd()).sort().join(',') === procCwdBefore, '§16c 进程 cwd 零新增文件');
+    // ---- §16d 直接调用能力层同样 fail closed(不依赖工具层守卫) ----
+    for (const bad of ['', '   ', undefined]) {
+        const r = await generateItineraryDeckArtifact({ title: TITLE, itinerary: ITINERARY, fact_ids: [] }, { stateRoot, cwd: bad });
+        ok(r.ok === false && /会话工作目录/.test(String(r.error)), `§16e 能力层拒绝 cwd=${JSON.stringify(bad)}`);
+    }
+    ok(readdirSync(process.cwd()).sort().join(',') === procCwdBefore, '§16f 能力层非法 cwd 零写入进程 cwd');
+    // ---- §17 真实产出链路:注册工具生成 → gotry_artifacts_list → gotry_artifacts_read ----
+    const listTool = tools.get('gotry_artifacts_list');
+    const readTool = tools.get('gotry_artifacts_read');
+    ok(Boolean(listTool && readTool), '§17a 产物 list/read 注册工具可用');
+    const chainName = 'gotry-deck-e2e-chain.html';
+    const chain = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [FLIGHT_ID, HOTEL_ID, TRAIN_ID], basename: chainName });
+    ok(chain.ok === true, `§17b 生成成功(实际:${JSON.stringify(chain.error ?? '')})`);
+    const chainDisk = readFileSync(String(chain.path), 'utf-8');
+    const listed = await listTool.execute({ limit: 50 }, exec);
+    const entry = (listed.artifacts ?? []).find(a => a.id === chainName);
+    ok(Boolean(entry), '§17c list 在册发现生成的 deck HTML(同一文件)');
+    ok(entry?.source === 'cwd-file', '§17d 来源为会话工作目录文件');
+    ok(realpathSync(String(entry?.path)) === String(chain.path), '§17e list 路径解析到生成返回的同一真实路径');
+    ok(entry?.bytes === Buffer.byteLength(chainDisk, 'utf8'), '§17f list 字节数与磁盘一致');
+    const read = await readTool.execute({ path: String(entry?.path) }, exec);
+    ok(read.ok === true, `§17g read 成功(实际:${JSON.stringify(read.error ?? '')})`);
+    ok(read.lang === 'html', '§17h read 以 html 源码文本读出');
+    ok(read.content === chainDisk, '§17i read 内容与落盘字节逐字一致');
+    ok(read.version === createHash('sha256').update(chainDisk).digest('hex').slice(0, 12), '§17j content version 与磁盘 sha256 指纹一致');
+    ok(read.content === renderDeck([FLIGHT, HOTEL, TRAIN]), '§17k 读回内容 == 注册表选中事实的 deck 输出');
+    // ---- §18 路径保真:宿主 cwd 的尾随空格是路径的一部分,绝不 trim 归一化到同名兄弟目录 ----
+    const plainDir = join(home, 'session');
+    const spacedDir = join(home, 'session ');
+    mkdirSync(plainDir, { recursive: true });
+    mkdirSync(spacedDir, { recursive: true });
+    const spacedExec = { agent: { session: { header: { cwd: spacedDir } } } };
+    const viaTool = await run({ title: TITLE, itinerary: ITINERARY, fact_ids: [], basename: 'gotry-deck-spaced.html' }, spacedExec);
+    ok(viaTool.ok === true, `§18a 带尾随空格的会话 cwd 生成成功(实际:${JSON.stringify(viaTool.error ?? '')})`);
+    ok(String(viaTool.path) === join(realpathSync(spacedDir), 'gotry-deck-spaced.html'), '§18b 落点 = 宿主给出的带空格目录');
+    ok(readdirSync(spacedDir).includes('gotry-deck-spaced.html'), '§18c 文件确实写在带空格目录内');
+    ok(deckFiles(plainDir).length === 0, '§18d 同名兄弟目录零写入(工具层未归一化)');
+    const viaCap = await generateItineraryDeckArtifact({ title: TITLE, itinerary: ITINERARY, fact_ids: [], basename: 'gotry-deck-spaced2.html' }, { stateRoot, cwd: spacedDir });
+    ok(viaCap.ok === true && readdirSync(spacedDir).includes('gotry-deck-spaced2.html'), '§18e 能力层写进带空格目录');
+    ok(deckFiles(plainDir).length === 0, '§18f 能力层不落到同名兄弟目录');
+    const plainOnly = join(home, 'plainonly');
+    mkdirSync(plainOnly, { recursive: true });
+    const ghost = await generateItineraryDeckArtifact({ title: TITLE, itinerary: ITINERARY, fact_ids: [] }, { stateRoot, cwd: `${plainOnly} ` });
+    ok(ghost.ok === false, '§18g 带空格路径不存在时拒绝(绝不回落 trim 后的兄弟)');
+    ok(readdirSync(plainOnly).length === 0, '§18h trim 后的兄弟目录零写入');
+    rmSync(home, { recursive: true, force: true });
+    console.log(`\nITINERARY DECK ARTIFACT TESTS: ${pass} pass, ${fail} fail`);
+    if (fail > 0) {
+        console.log('\nFAILURES:');
+        for (const f of failures)
+            console.log(`  - ${f}`);
+        process.exit(1);
+    }
+}
+await main();