@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/dist/scripts/dsh-runtime-closure-tests.js

@@ -0,0 +1,182 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { parsePnpmDshLock, parsePnpmRootDshImporter, REQUIRED_DSH_RUNTIME_PACKAGE_COUNT, validateDshRuntimeClosure, validatePnpmRootDshImporter, } from './dsh-runtime-closure.js';
+const VERSION = '0.2.0-rc.2';
+function validInput() {
+    return {
+        dependencies: {
+            '@deepseek-ai/dsh': VERSION,
+            '@deepseek-ai/dsh-session-title': VERSION,
+        },
+        lockPackages: {
+            'node_modules/@deepseek-ai/dsh': { version: VERSION },
+            'node_modules/@deepseek-ai/dsh-session-title': { version: VERSION },
+        },
+        runtimeVersion: VERSION,
+    };
+}
+test('accepts an exact coherent DSH prerelease closure', () => {
+    assert.deepEqual(validateDshRuntimeClosure(validInput()), {
+        names: ['@deepseek-ai/dsh', '@deepseek-ai/dsh-session-title'],
+        version: VERSION,
+    });
+});
+test('rejects a lock package missing from the published direct dependencies', () => {
+    const input = validInput();
+    input.dependencies = { '@deepseek-ai/dsh': VERSION };
+    assert.throws(() => validateDshRuntimeClosure(input), /DSH closure 未精确声明/);
+});
+test('rejects an extra ranged DSH dependency absent from the tested lock closure', () => {
+    const input = validInput();
+    input.dependencies['@deepseek-ai/dsh-web'] = '^0.2.0-rc.2';
+    assert.throws(() => validateDshRuntimeClosure(input), /DSH manifest 与 lock 集合不一致/);
+});
+test('rejects a nested DSH package from another prerelease', () => {
+    const input = validInput();
+    input.lockPackages['node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-session-title'] = {
+        version: '0.1.5-alpha.2',
+    };
+    assert.throws(() => validateDshRuntimeClosure(input), /DSH lock 版本漂移/);
+});
+test('rejects drift from the runtime spawn guard version', () => {
+    const input = validInput();
+    input.runtimeVersion = '0.1.5-alpha.2';
+    assert.throws(() => validateDshRuntimeClosure(input), /DSH runtime guard 版本漂移/);
+});
+test('parses each pnpm DSH resolution once across packages and snapshots', () => {
+    const lock = `
+packages:
+  '@deepseek-ai/dsh@0.2.0-rc.2': {}
+  '@deepseek-ai/dsh-session@0.2.0-rc.2': {}
+snapshots:
+  '@deepseek-ai/dsh@0.2.0-rc.2': {}
+`;
+    assert.deepEqual(parsePnpmDshLock(lock), {
+        'node_modules/@deepseek-ai/dsh': { version: VERSION },
+        'node_modules/@deepseek-ai/dsh-session': { version: VERSION },
+    });
+});
+test('preserves two pnpm resolutions of the same DSH package for mixed-version rejection', () => {
+    const lock = `
+packages:
+  '@deepseek-ai/dsh@0.2.0-rc.2': {}
+  '@deepseek-ai/dsh-session@0.2.0-rc.2': {}
+  '@deepseek-ai/dsh-session@0.1.5-alpha.2': {}
+`;
+    const parsed = parsePnpmDshLock(lock);
+    assert.equal(Object.keys(parsed).length, 3);
+    assert.throws(() => validateDshRuntimeClosure({
+        dependencies: {
+            '@deepseek-ai/dsh': VERSION,
+            '@deepseek-ai/dsh-session': VERSION,
+        },
+        lockPackages: parsed,
+        runtimeVersion: VERSION,
+    }), /DSH lock 版本漂移/);
+});
+test('parses only the root pnpm importer DSH entries', () => {
+    const lock = `
+lockfileVersion: '9.0'
+importers:
+  .:
+    dependencies:
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2(peer@1.0.0)
+      '@deepseek-ai/dsh-session':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2
+  ts:
+    dependencies:
+      '@deepseek-ai/dsh-web':
+        specifier: 0.1.5-alpha.2
+        version: 0.1.5-alpha.2
+packages: {}
+`;
+    assert.deepEqual(parsePnpmRootDshImporter(lock), {
+        '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: VERSION },
+        '@deepseek-ai/dsh-session': { specifier: VERSION, resolvedVersion: VERSION },
+    });
+});
+test('rejects a pnpm root importer missing a published DSH dependency', () => {
+    assert.throws(() => validatePnpmRootDshImporter({
+        dependencies: validInput().dependencies,
+        importerEntries: {
+            '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: VERSION },
+        },
+        runtimeVersion: VERSION,
+    }), /pnpm root importer 与 manifest 集合不一致/);
+});
+test('rejects a ranged DSH specifier in the pnpm root importer', () => {
+    assert.throws(() => validatePnpmRootDshImporter({
+        dependencies: validInput().dependencies,
+        importerEntries: {
+            '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: VERSION },
+            '@deepseek-ai/dsh-session-title': { specifier: '^0.2.0-rc.2', resolvedVersion: VERSION },
+        },
+        runtimeVersion: VERSION,
+    }), /pnpm root importer 未精确锁定/);
+});
+test('rejects a drifted resolved DSH version in the pnpm root importer', () => {
+    assert.throws(() => validatePnpmRootDshImporter({
+        dependencies: validInput().dependencies,
+        importerEntries: {
+            '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: '0.1.5-alpha.2' },
+            '@deepseek-ai/dsh-session-title': { specifier: VERSION, resolvedVersion: VERSION },
+        },
+        runtimeVersion: VERSION,
+    }), /pnpm root importer resolved 版本漂移/);
+});
+test('rejects a missing resolved DSH version in the pnpm root importer', () => {
+    const lock = `
+importers:
+  .:
+    dependencies:
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+`;
+    assert.throws(() => parsePnpmRootDshImporter(lock), /pnpm root importer version 不可用/);
+});
+test('rejects duplicate resolved DSH versions in the pnpm root importer', () => {
+    const lock = `
+importers:
+  .:
+    dependencies:
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2
+        version: 0.1.5-alpha.2
+`;
+    assert.throws(() => parsePnpmRootDshImporter(lock), /pnpm root importer version 不可用/);
+});
+test('rejects a coherent closure below the required package count', () => {
+    assert.throws(() => validateDshRuntimeClosure({
+        ...validInput(),
+        expectedPackageCount: REQUIRED_DSH_RUNTIME_PACKAGE_COUNT,
+    }), /DSH closure 包数量不符/);
+});
+test('rejects a coherent root importer below the required package count', () => {
+    assert.throws(() => validatePnpmRootDshImporter({
+        dependencies: validInput().dependencies,
+        importerEntries: {
+            '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: VERSION },
+            '@deepseek-ai/dsh-session-title': { specifier: VERSION, resolvedVersion: VERSION },
+        },
+        runtimeVersion: VERSION,
+        expectedPackageCount: REQUIRED_DSH_RUNTIME_PACKAGE_COUNT,
+    }), /pnpm root importer 包数量不符/);
+});
+test('rejects duplicate DSH entries in the pnpm root importer', () => {
+    const lock = `
+importers:
+  .:
+    dependencies:
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2
+`;
+    assert.throws(() => parsePnpmRootDshImporter(lock), /pnpm root importer DSH 依赖重复/);
+});

package/dist/scripts/dsh-runtime-closure.js

@@ -0,0 +1,162 @@
+export const REQUIRED_DSH_RUNTIME_PACKAGE_COUNT = 279;
+function yamlScalar(value) {
+    const trimmed = value.trim().replace(/\s+#.*$/, '');
+    const quoted = trimmed.match(/^(['"])(.*)\1$/);
+    return quoted?.[2] ?? trimmed;
+}
+function indentation(line) {
+    return line.match(/^ */)?.[0].length ?? 0;
+}
+function resolvedPnpmVersion(value) {
+    return yamlScalar(value).replace(/\(.+$/, '');
+}
+export function parsePnpmRootDshImporter(text) {
+    const lines = text.split(/\r?\n/);
+    const importers = lines
+        .map((line, index) => line === 'importers:' ? index : -1)
+        .filter((index) => index >= 0);
+    if (importers.length !== 1)
+        throw new Error('pnpm lock importers 区块不可用');
+    const importersStart = importers[0];
+    const importersEnd = lines.findIndex((line, index) => index > importersStart && line.trim() !== '' && indentation(line) === 0);
+    const rootCandidates = lines
+        .map((line, index) => index > importersStart && (importersEnd < 0 || index < importersEnd)
+        && /^ {2}(?:\.|'\.'|"\."):\s*$/.test(line) ? index : -1)
+        .filter((index) => index >= 0);
+    if (rootCandidates.length !== 1)
+        throw new Error('pnpm root importer 不唯一');
+    const rootStart = rootCandidates[0];
+    const rootEndRelative = lines.slice(rootStart + 1, importersEnd < 0 ? lines.length : importersEnd)
+        .findIndex((line) => line.trim() !== '' && indentation(line) <= 2);
+    const rootEnd = rootEndRelative < 0
+        ? (importersEnd < 0 ? lines.length : importersEnd)
+        : rootStart + 1 + rootEndRelative;
+    const dependencyBlocks = lines
+        .map((line, index) => index > rootStart && index < rootEnd && /^ {4}dependencies:\s*$/.test(line) ? index : -1)
+        .filter((index) => index >= 0);
+    if (dependencyBlocks.length !== 1)
+        throw new Error('pnpm root importer dependencies 区块不可用');
+    const dependenciesStart = dependencyBlocks[0];
+    const dependenciesEndRelative = lines.slice(dependenciesStart + 1, rootEnd)
+        .findIndex((line) => line.trim() !== '' && indentation(line) <= 4);
+    const dependenciesEnd = dependenciesEndRelative < 0 ? rootEnd : dependenciesStart + 1 + dependenciesEndRelative;
+    const entries = lines
+        .map((line, index) => {
+        if (index <= dependenciesStart || index >= dependenciesEnd)
+            return null;
+        const match = line.match(/^ {6}(['"]?)([^'":\s]+)\1:\s*$/);
+        return match ? { index, name: match[2] } : null;
+    })
+        .filter((entry) => entry !== null);
+    const importerEntries = {};
+    for (let entryIndex = 0; entryIndex < entries.length; entryIndex += 1) {
+        const entry = entries[entryIndex];
+        if (entry.name !== '@deepseek-ai/dsh' && !entry.name.startsWith('@deepseek-ai/dsh-'))
+            continue;
+        if (Object.hasOwn(importerEntries, entry.name))
+            throw new Error(`pnpm root importer DSH 依赖重复:${entry.name}`);
+        const end = entries[entryIndex + 1]?.index ?? dependenciesEnd;
+        const block = lines.slice(entry.index + 1, end);
+        const specifiers = block
+            .map((line) => line.match(/^ {8}specifier:\s*(.+)$/)?.[1])
+            .filter((value) => value !== undefined);
+        if (specifiers.length !== 1)
+            throw new Error(`pnpm root importer specifier 不可用:${entry.name}`);
+        const versions = block
+            .map((line) => line.match(/^ {8}version:\s*(.+)$/)?.[1])
+            .filter((value) => value !== undefined);
+        if (versions.length !== 1)
+            throw new Error(`pnpm root importer version 不可用:${entry.name}`);
+        importerEntries[entry.name] = {
+            specifier: yamlScalar(specifiers[0]),
+            resolvedVersion: resolvedPnpmVersion(versions[0]),
+        };
+    }
+    return importerEntries;
+}
+export function validatePnpmRootDshImporter(input) {
+    const manifestNames = Object.keys(input.dependencies)
+        .filter((name) => name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-'))
+        .sort();
+    const importerNames = Object.keys(input.importerEntries).sort();
+    const missing = manifestNames.filter((name) => !importerNames.includes(name));
+    const extra = importerNames.filter((name) => !manifestNames.includes(name));
+    if (missing.length > 0 || extra.length > 0) {
+        throw new Error(`pnpm root importer 与 manifest 集合不一致:missing=${missing.join(',') || '-'};extra=${extra.join(',') || '-'}`);
+    }
+    for (const name of importerNames) {
+        const importerEntry = input.importerEntries[name];
+        if (input.dependencies[name] !== input.runtimeVersion || importerEntry.specifier !== input.runtimeVersion) {
+            throw new Error(`pnpm root importer 未精确锁定:${name}@${input.runtimeVersion}`);
+        }
+        if (importerEntry.resolvedVersion !== input.runtimeVersion) {
+            throw new Error(`pnpm root importer resolved 版本漂移:${name}@${importerEntry.resolvedVersion}(expected ${input.runtimeVersion})`);
+        }
+    }
+    if (input.expectedPackageCount !== undefined && importerNames.length !== input.expectedPackageCount) {
+        throw new Error(`pnpm root importer 包数量不符:${importerNames.length}(expected ${input.expectedPackageCount})`);
+    }
+    return { names: importerNames, version: input.runtimeVersion };
+}
+export function parsePnpmDshLock(text) {
+    const packages = {};
+    const seen = new Set();
+    const variants = new Map();
+    const entry = /^\s{2}['"]?(\@deepseek-ai\/dsh(?:-[^@'":\s]+)?)@([^'":\s(]+)(?:\([^'"]*\))?['"]?:/gm;
+    for (const match of text.matchAll(entry)) {
+        const name = match[1];
+        const version = match[2];
+        const identity = `${name}@${version}`;
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        const variant = variants.get(name) ?? 0;
+        variants.set(name, variant + 1);
+        const prefix = variant === 0 ? '' : `.pnpm-variant-${variant}/node_modules/`;
+        packages[`node_modules/${prefix}${name}`] = { version };
+    }
+    return packages;
+}
+export function validateDshRuntimeClosure(input) {
+    const dshVersion = input.dependencies['@deepseek-ai/dsh'];
+    if (typeof dshVersion !== 'string' || !/^\d+\.\d+\.\d+-[0-9A-Za-z.-]+$/.test(dshVersion)) {
+        throw new Error('@deepseek-ai/dsh 必须以精确 prerelease 版本声明');
+    }
+    if (dshVersion !== input.runtimeVersion) {
+        throw new Error(`DSH runtime guard 版本漂移:${input.runtimeVersion}(manifest ${dshVersion})`);
+    }
+    const dshNodes = Object.entries(input.lockPackages)
+        .flatMap(([path, metadata]) => {
+        const match = path.match(/(?:^|\/)node_modules\/(\@deepseek-ai\/dsh(?:-[^/]+)?)$/);
+        return match ? [{ name: match[1], version: metadata.version }] : [];
+    })
+        .sort((left, right) => left.name.localeCompare(right.name));
+    if (dshNodes.length === 0)
+        throw new Error('package-lock 未解析到 DSH runtime closure');
+    for (const dependency of dshNodes) {
+        if (dependency.version !== dshVersion) {
+            throw new Error(`DSH lock 版本漂移:${dependency.name}@${dependency.version ?? 'missing'}(expected ${dshVersion})`);
+        }
+    }
+    const lockNames = [...new Set(dshNodes.map((dependency) => dependency.name))].sort();
+    const manifestNames = Object.keys(input.dependencies)
+        .filter((name) => name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-'))
+        .sort();
+    const missing = lockNames.filter((name) => !manifestNames.includes(name));
+    const extra = manifestNames.filter((name) => !lockNames.includes(name));
+    if (missing.length > 0) {
+        throw new Error(`DSH closure 未精确声明:${missing[0]}@${dshVersion}`);
+    }
+    if (extra.length > 0) {
+        throw new Error(`DSH manifest 与 lock 集合不一致:missing=${missing.join(',') || '-'};extra=${extra.join(',') || '-'}`);
+    }
+    for (const name of manifestNames) {
+        if (input.dependencies[name] !== dshVersion) {
+            throw new Error(`DSH closure 未精确声明:${name}@${dshVersion}`);
+        }
+    }
+    if (input.expectedPackageCount !== undefined && lockNames.length !== input.expectedPackageCount) {
+        throw new Error(`DSH closure 包数量不符:${lockNames.length}(expected ${input.expectedPackageCount})`);
+    }
+    return { names: lockNames, version: dshVersion };
+}

package/dist/scripts/dsh-session-v3-migration-proof.js

@@ -0,0 +1,109 @@
+/**
+ * Session V3 确定性迁移契约(issue #268):在隔离临时目录下用真实发布的 V2 编解码器
+ * 生成 V2 header/events,序列化为 JSONL 字节写入磁盘,保存确切源字节快照;通过
+ * sessionFormatCatalog 从磁盘读取并解析这些字节,分类为 migration-required,迁移为
+ * V3,编码独立 V3 继任者写入磁盘;然后用 catalog validation:current 完全解码 V3
+ * 继任者;迁移后重新读取 V2 源文件做字节比较,证明迁移不修改源工件字节。
+ *
+ * 这是确定性格式兼容性证据(隔离文件字节,非内存 structuredClone),不是创始人状态
+ * 迁移,也不是 M5/M6 准入。
+ *
+ * 运行:cd ts && npx tsx scripts/dsh-session-v3-migration-proof.ts
+ */
+import assert from 'node:assert/strict';
+import { writeFileSync, readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createSessionFormatCatalogWithChildren } from '@deepseek-ai/dsh-session-format-catalog';
+import { releasedV2SessionFormatCodec } from '@deepseek-ai/dsh-session-format-v1-to-v2';
+// 最小有效 V2 工件:一个 turn 包含一个 step,turn 正常完成。
+// V2 事件处置要求 turn/start 需 ["turn"],step/start|step/end 需 ["turn","step"],
+// turn/end 需 ["turn","reason"],reason.kind="completed" 是最简有效种类。
+const v2Header = {
+    version: 2,
+    id: 's-min-v2',
+    createdAt: 1700000000000,
+    isSeeded: false,
+    delegationDepth: 0,
+};
+const v2Events = [
+    { type: 'turn/start', seq: 0, time: 1700000000000, data: { turn: 1 } },
+    { type: 'step/start', seq: 1, time: 1700000000001, data: { turn: 1, step: 1 } },
+    { type: 'step/end', seq: 2, time: 1700000000002, data: { turn: 1, step: 1 } },
+    { type: 'turn/end', seq: 3, time: 1700000000003, data: { turn: 1, reason: { kind: 'completed' } } },
+];
+// 1. 用真实发布的 V2 编解码器编码 header + 事件行为 JSON 对象,序列化为 JSONL 字节。
+const encodedHeader = releasedV2SessionFormatCodec.encodeHeader(v2Header, 0);
+const encodedRows = v2Events.map((e) => releasedV2SessionFormatCodec.encodeEvent(e));
+function toLine(obj) {
+    return JSON.stringify(obj);
+}
+const sourceLines = [toLine(encodedHeader), ...encodedRows.map(toLine)];
+const sourceJsonl = sourceLines.join('\n') + '\n';
+const tmp = mkdtempSync(join(tmpdir(), 'session-v3-migration-proof-'));
+const sourcePath = join(tmp, 'source.v2.jsonl');
+const successorPath = join(tmp, 'successor.current.jsonl');
+// 0.2.0-rc.2 起 catalog current = V4;V3→V4 边要求显式历史子代理证据,
+// 本 fixture 是无父会话,声明空数组(createSessionFormatCatalogWithChildren)。
+const catalog = createSessionFormatCatalogWithChildren([]);
+try {
+    // 2. 写 V2 源字节到磁盘,保存确切源字节快照。
+    writeFileSync(sourcePath, sourceJsonl, 'utf8');
+    const sourceBytes = readFileSync(sourcePath);
+    // 3. 从磁盘读取并解析 V2 源字节:首行 = header,其余 = 事件行。
+    const parsedLines = readFileSync(sourcePath, 'utf8').split('\n').filter((l) => l.length > 0);
+    assert.ok(parsedLines.length === sourceLines.length, `磁盘行数必须等于源行数(${parsedLines.length} vs ${sourceLines.length})`);
+    const headerValue = JSON.parse(parsedLines[0]);
+    const rowValues = parsedLines.slice(1).map((l) => JSON.parse(l));
+    // 4. catalog 当前版本 = 4(0.2.0-rc.2 起);V2 header 分类为 migration-required。
+    assert.equal(catalog.currentVersion, 4, 'catalog 当前版本必须为 4(0.2.0-rc.2 起 V4 为 current)');
+    const headerRead = catalog.readHeader(headerValue);
+    assert.equal(headerRead.status, 'migration-required', `V2 header 必须分类为 migration-required(当前 ${headerRead.status})`);
+    // 5. 创建恢复器,逐行解码,完成恢复为 V3 工件(validation:transformed,迁移后校验)。
+    const restore = catalog.createRestore(headerValue, {
+        recovery: 'recoverable',
+        validation: 'transformed',
+    });
+    for (const row of rowValues) {
+        restore.decodeRow(row);
+    }
+    const artifact = restore.finish();
+    // 6. 迁移链工件版本 = 4(V2→V3 插入 system head 后,V3→V4 不减事件)。
+    assert.equal(artifact.header.version, 4, '恢复后工件版本必须为 4');
+    assert.ok(artifact.events.length >= v2Events.length + 1, `迁移链事件数必须 ≥ V2 + 1(插入 system head),当前 ${artifact.events.length}`);
+    // 插入的 system head(原 step/start 后)必须是 system/message。
+    const inserted = artifact.events.find((event) => event.type === 'system/message');
+    assert.ok(inserted, '迁移链必须包含插入的 system/message head');
+    // 7. 编码 current(V4)继任者为 JSONL 字节,写入独立磁盘文件。
+    const currentHeaderRecord = catalog.encodeCurrentHeader(artifact.header, artifact.inheritedEventCount);
+    const currentRowRecords = artifact.events.map((e) => catalog.encodeCurrentEvent(e));
+    const successorLines = [toLine(currentHeaderRecord), ...currentRowRecords.map(toLine)];
+    const successorJsonl = successorLines.join('\n') + '\n';
+    writeFileSync(successorPath, successorJsonl, 'utf8');
+    // 8. 从磁盘读取 V3 继任者,用 catalog validation:current 完全解码。
+    const successorParsed = readFileSync(successorPath, 'utf8').split('\n').filter((l) => l.length > 0);
+    assert.ok(successorParsed.length === successorLines.length, `V3 磁盘行数必须等于继任者行数`);
+    const successorHeaderValue = JSON.parse(successorParsed[0]);
+    const successorRowValues = successorParsed.slice(1).map((l) => JSON.parse(l));
+    const successorRead = catalog.readHeader(successorHeaderValue);
+    assert.equal(successorRead.status, 'current', `V3 继任者必须重新打开为 current(当前 ${successorRead.status})`);
+    const successorRestore = catalog.createRestore(successorHeaderValue, {
+        recovery: 'recoverable',
+        validation: 'current',
+    });
+    for (const row of successorRowValues) {
+        successorRestore.decodeRow(row);
+    }
+    const successorArtifact = successorRestore.finish();
+    assert.equal(successorArtifact.header.version, 4, 'current 继任者完全解码后版本必须为 4');
+    assert.equal(successorArtifact.events.length, artifact.events.length, 'V3 继任者完全解码后事件数必须与迁移工件一致');
+    // 9. 迁移后重新读取 V2 源文件字节,与快照字节比较——证明迁移不修改源工件字节。
+    const sourceBytesAfter = readFileSync(sourcePath);
+    assert.ok(Buffer.compare(sourceBytes, sourceBytesAfter) === 0, '迁移后 V2 源文件字节必须与快照完全一致——迁移不修改源工件字节');
+    console.log(`SESSION V3 MIGRATION PROOF: V2 source ${sourceBytes.length}B (${v2Events.length} events) on disk → ` +
+        `current V4(${artifact.events.length} events, +system/message), successor ${successorJsonl.length}B reopens as current ` +
+        `and fully decodes (${successorArtifact.events.length} events), source bytes unchanged after migration`);
+}
+finally {
+    rmSync(tmp, { recursive: true, force: true });
+}

package/dist/scripts/dsh-subprocess-local-proof.js

@@ -0,0 +1,150 @@
+/**
+ * dsh-subprocess-local 确定性证明(issue #268):仅通过公共 API 挂载 provider,
+ * 执行真实的本地托管子进程与 PTY,观察真实输出,终止它,await 公共 waitForExit,
+ * 并证明派生后代已消失。平台中立(Ubuntu CI + macOS)——不调用私有
+ * selectContainmentMode()/disposeManagedProcesses(),不断言主机是 macOS fallback,
+ * 不用已退出的顶层进程作为后代清理替代。
+ *
+ * 公共挂载模式:await ctx.plugin(LocalSubprocessRuntime) → ctx.subprocess 可用。
+ * spawn 一个活跃的 node 父进程(被 provider 以 detached:true 启动,自成进程组领袖),
+ * 该父进程用 child_process.spawn 创建一个非分离的真实长运行子进程(继承父进程组),
+ * 并将子进程 PID 输出到 stdout。证明通过收集 stdout 读取子进程 PID,调用公共
+ * terminate() + await waitForExit(有界 abort 信号),断言父进程结果和子进程 PID
+ * 都已消失(进程组信号终止整个组)。
+ *
+ * 真实 PTY 验证在 CI 支持平台(Linux/macOS)都执行:spawnTerminal 启动 node 子进程,
+ * 子进程向 stdout 写入 'pty-line\n' 并正常退出;断言 PTY 输出包含 'pty-line' 且 exitCode=0。
+ * 目标 node-pty 包的 Darwin 预构建同时带 `pty.node` 与 `spawn-helper`，Linux x64/arm64
+ * 预构建只带 `pty.node`。本证明在两个平台都跑真实 PTY 行为；filesystem 上
+ * spawn-helper 存在性与 0755 模式断言仅在 Darwin 下生效。Linux 报告
+ * "helper not-applicable"，同时仍验证真实 PTY 输出与成功退出，不 stat 不存在的文件。
+ *
+ * finally 中 await ctx.fiber.dispose() 并移除临时文件。不向子进程传递整个环境变量。
+ *
+ * 运行:cd ts && npx tsx scripts/dsh-subprocess-local-proof.ts
+ */
+import assert from 'node:assert/strict';
+import { writeFileSync, mkdtempSync, rmSync, existsSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { Context } from '@deepseek-ai/cordis';
+import { LocalSubprocessRuntime } from '@deepseek-ai/dsh-subprocess-local';
+const ctx = new Context();
+const fiber = ctx.plugin(LocalSubprocessRuntime);
+await fiber;
+const tmp = mkdtempSync(join(tmpdir(), 'subprocess-local-proof-'));
+let childPid;
+let childGoneAfter = false;
+let parentOutcome;
+let rangeEmpty;
+let ptyExitCode = null;
+let ptyOutput = '';
+let helperFact;
+let helperMode;
+try {
+    // 1. 父进程脚本:spawn 一个非分离的长运行子进程(继承父进程组),输出子进程 PID。
+    //    父进程自身保持活跃(setInterval),直到被 provider 终止。
+    const parentScript = join(tmp, 'parent.mjs');
+    writeFileSync(parentScript, [
+        "import { spawn } from 'node:child_process'",
+        "const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 60000)'], { stdio: 'inherit' })",
+        "process.stdout.write('CHILD_PID=' + child.pid + '\\n')",
+        'setInterval(() => {}, 60000)',
+        '',
+    ].join('\n'));
+    // 2. 通过公共 ctx.subprocess.spawn 启动父进程。不传 env——让 provider 用
+    //    scrubbedParentEnv() 清洗环境(保留 PATH/HOME,剥离凭据/DSH_*),不传递整个环境变量。
+    const handle = ctx.subprocess.spawn({
+        argv: [process.execPath, parentScript],
+        cwd: tmp,
+        stdio: { stdin: 'ignore', stdout: { maxBytes: 1 << 20 }, stderr: { maxBytes: 1 << 20 } },
+        graceMs: 8000,
+    });
+    const stdoutReader = handle.collected.stdout;
+    assert.ok(stdoutReader, 'collect 模式下 collected.stdout reader 必须存在');
+    // 3. 通过观察父进程输出获取子进程 PID(有界轮询,不假设即时可用)。
+    let observedChildPid;
+    const pollDeadline = Date.now() + 5000;
+    while (Date.now() < pollDeadline && observedChildPid === undefined) {
+        const read = stdoutReader.readFrom(0);
+        const m = /CHILD_PID=(\d+)/.exec(read.text);
+        if (m)
+            observedChildPid = Number(m[1]);
+        else
+            await new Promise((r) => setTimeout(r, 20));
+    }
+    assert.ok(observedChildPid !== undefined && observedChildPid > 0, `必须从父进程 stdout 观察到有效 CHILD_PID(当前 ${observedChildPid})`);
+    childPid = observedChildPid;
+    // 4. 终止前:子进程必须存活(父进程已 spawn 它)。
+    assert.ok(isPidAlive(childPid), `终止前子进程 PID ${childPid} 必须存活`);
+    // 5. 调用公共 terminate() + await 公共 waitForExit(有界 abort 信号)。
+    //    进程组信号(process.kill(-parentPid, SIGTERM))终止整个组,包括非分离子进程。
+    handle.terminate();
+    rangeEmpty = await handle.waitForExit(AbortSignal.timeout(8000));
+    assert.equal(rangeEmpty, true, 'waitForExit 必须返回 true——托管范围(含后代)已空');
+    // 6. 断言直接进程结果:父进程被信号终止(非正常退出)。
+    parentOutcome = await handle.done;
+    assert.ok(parentOutcome.exitCode === null && parentOutcome.signal !== null, `父进程必须被信号终止(exitCode=${parentOutcome.exitCode}, signal=${parentOutcome.signal})`);
+    // 7. 断言子进程 PID 不再存在——后代清理的真实证据(非已退出顶层进程替代)。
+    childGoneAfter = !isPidAlive(childPid);
+    assert.ok(childGoneAfter, `provider 终止后子进程 PID ${childPid} 必须已消失——进程组包含的真实后代清理证据`);
+    // 8. 真实 PTY 验证(每个支持平台都执行):spawnTerminal 用 native PTY 后端 fork/exec,
+    //    子进程写 'pty-line\n' 并正常退出。原生 PTY 输出经 PTY 终端层到达 PTY 主面,
+    //    再被 node-pty 回调成 output 'data' 事件——这是跨平台的 PTY 行为证明。
+    const ptyScript = join(tmp, 'pty.mjs');
+    writeFileSync(ptyScript, "process.stdout.write('pty-line\\n'); process.exit(0);\n");
+    const term = await ctx.subprocess.spawnTerminal({
+        argv: [process.execPath, ptyScript],
+        cwd: tmp,
+        rows: 24,
+        cols: 80,
+        terminalType: 'xterm-256color',
+        graceMs: 8000,
+    });
+    assert.equal(typeof term.pid, 'number', `PTY pid 必须是数字(当前 ${typeof term.pid})`);
+    assert.ok(term.pid > 0, `PTY pid 必须为正(当前 ${term.pid})`);
+    term.output.on('data', (d) => {
+        ptyOutput += d.toString();
+    });
+    const termOutcome = await term.done;
+    ptyExitCode = termOutcome.exitCode;
+    assert.equal(ptyExitCode, 0, `PTY 必须正常退出(exitCode=${ptyExitCode})`);
+    assert.equal(termOutcome.signal, null, `PTY 正常退出不得携带 signal(当前 ${termOutcome.signal})`);
+    assert.ok(ptyOutput.includes('pty-line'), `PTY 输出必须包含 pty-line(当前 ${JSON.stringify(ptyOutput)})`);
+    await term.terminate();
+    // 9. node-pty spawn-helper 文件系统断言仅在 Darwin 下生效。
+    //    已检查的目标包事实:darwin-{x64,arm64}/prebuilds 同时带 pty.node 与
+    //    spawn-helper，linux-{x64,arm64}/prebuilds 仅带 pty.node。本证明不构造、
+    //    不复制、不 stat 实际不存在的 helper。
+    helperMode = null;
+    if (process.platform === 'darwin') {
+        const ptyEntry = fileURLToPath(import.meta.resolve('node-pty'));
+        const ptyRoot = dirname(dirname(ptyEntry));
+        const helperPath = join(ptyRoot, 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper');
+        assert.ok(existsSync(helperPath), `Darwin prebuilds 必须携带 spawn-helper(实际不存在:${helperPath})——ensure-spawn-helper.mjs 的终局面契约`);
+        helperMode = statSync(helperPath).mode & 0o777;
+        assert.equal(helperMode, 0o755, `Darwin spawn-helper 权限模式必须是 0755(当前 0o${helperMode.toString(8)})——ensure-spawn-helper.mjs 的终局面契约`);
+        helperFact = `helper=darwin 0o${helperMode.toString(8)}`;
+    }
+    else {
+        helperFact = `helper=not-applicable:${process.platform}-${process.arch}; real PTY output='pty-line' present, exitCode=0`;
+        assert.ok(ptyExitCode === 0 && ptyOutput.includes('pty-line'), '非 Darwin 平台必须仍证明真实 PTY 行为:PTY 输出包含 pty-line 且 exitCode=0');
+    }
+    console.log(`SUBPROCESS LOCAL PROOF: parent killed by signal ${parentOutcome.signal}, child PID ${childPid} gone after terminate=${childGoneAfter}, ` +
+        `waitForExit rangeEmpty=${rangeEmpty}, PTY pid=${term.pid} exitCode=${ptyExitCode} output-has-pty-line=${ptyOutput.includes('pty-line')}, ` +
+        `${helperFact}`);
+}
+finally {
+    await ctx.fiber.dispose();
+    rmSync(tmp, { recursive: true, force: true });
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}