@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/scripts/hbcli-e2e-tests.js

@@ -1,3 +1,24 @@
+/**
+ * staicli(hbcli)全流程端到端测试:二进制 → 隔离凭证面 → 真实 UAT 取票 →
+ * 能力层真实 spawn → 效应解译层策略(ADR-18)→ 工具层 gotry_hotel_search。
+ *
+ * 账号与凭证纪律(红线):
+ *   - 测试账号用 hotel-be 种子沙箱 API 账号 hotelbyte_api_demo/hotelbyte_api_demo
+ *     (user/domain/predefined_user_demo.go,IsSandbox:true,专为 API 接入验证设计);
+ *     正式集成方换自己申请的 hbk_ / hbs_ 前缀凭证对。
+ *   - 凭证写进 mkdtemp 的隔离 STAICLI_HOME,全程不读不写用户默认 ~/.staicli
+ *     (巡检状态纪律:测试不得触碰真实用户凭证与产品状态);
+ *   - stateRoot 同样走临时目录,结束即删。
+ *
+ * SKIP 语义(同 §17 先例:能跑则跑,环境缺前置不红):
+ *   - hbcli 未安装 → SKIP + 安装指引(npx @danceiny/gotry setup);
+ *   - UAT(api-test.hotelbyte.com)不可达 → SKIP + 原因。
+ * UAT 当前库存态(2026-08-30 实测):目的地/酒店参考数据为空,hotel-list 按名
+ * 查询返回业务层 404——通道/鉴权/搜索编排(供应商 provenance+correlationId)均
+ * 真实工作,故断言「通道真实性 + 降级诚实性」而非「有库存返回」。
+ *
+ * 运行(显式 UAT opt-in): cd ts && GOTRY_HBCLI_LIVE=1 npx tsx scripts/hbcli-e2e-tests.ts
+ */
 import { spawnSync } from 'node:child_process';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -6,121 +27,101 @@ import assert from 'node:assert/strict';
 import { listDestinations, searchHotels, hbcliBinCandidates } from '../capabilities/hbcli.js';
 import { makeProductionInterpreter } from '../capabilities/effect.js';
 const UAT = 'https://api-test.hotelbyte.com';
+/** hotel-be 种子沙箱 API 账号(公开演示用,IsSandbox;真实集成方应换自己申请的 hbk_/hbs_ 前缀凭证对) */
 const SANDBOX_APP_KEY = 'hotelbyte_api_demo';
 const SANDBOX_APP_SECRET = 'hotelbyte_api_demo';
 const GUIDANCE = [
     'staicli(hbcli)账号配置指引:',
-    '  1. 安装 CLI(若缺):npx gotry setup(npm 装 staicli@npmjs → PATH 的 hbcli)',
+    '  1. 安装 CLI(若缺):npx @danceiny/gotry setup(npm 装 staicli@npmjs → PATH 的 hbcli)',
     '  2. 快速试用(沙箱演示账号,来自 hotel-be 种子,user/domain/predefined_user_demo.go):',
     '     hbcli auth set-credentials --app-key hotelbyte_api_demo --app-secret hotelbyte_api_demo',
     '  3. 正式接入:向 HotelByte 申请专属 appKey/appSecret(hbk_*/hbs_*),替换第 2 步凭证;',
     '     门户模式则 hbcli auth login --username <email>(权限更大,搜索场景无必要)',
-    '  4. 自检:hbcli auth whoami(api_key.configured=true 即凭证就位;has_ticket 首次查询后为 true)'
+    '  4. 自检:hbcli auth whoami(api_key.configured=true 即凭证就位;has_ticket 首次查询后为 true)',
 ];
 function probeBin() {
-    for (const bin of hbcliBinCandidates('hbcli')){
-        const r = spawnSync(bin, [
-            'version'
-        ], {
-            timeout: 10_000,
-            stdio: 'ignore'
-        });
-        if (!r.error && r.status === 0) return bin;
+    for (const bin of hbcliBinCandidates('hbcli')) {
+        const r = spawnSync(bin, ['version'], { timeout: 10_000, stdio: 'ignore' });
+        if (!r.error && r.status === 0)
+            return bin;
     }
     return null;
 }
 async function uatReachable() {
     try {
         await fetch(`${UAT}/api/search/destinations`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json'
-            },
-            body: '{}',
-            signal: AbortSignal.timeout(8_000)
+            method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}',
+            signal: AbortSignal.timeout(8_000),
         });
-        return true;
-    } catch  {
+        return true; // 任何 HTTP 响应(含 401)都算可达
+    }
+    catch {
         return false;
     }
 }
 async function main() {
+    // This guard must stay before guidance-dependent probes, binary discovery,
+    // network reachability, STAICLI_HOME setup, and every credential operation.
+    // GOTRY_SESSION_LIVE intentionally does not control this supplier path.
+    if (process.env.GOTRY_HBCLI_LIVE !== '1') {
+        console.log('SKIP: HotelByte UAT 已关闭(默认离线);如需真实 UAT 请显式设置 GOTRY_HBCLI_LIVE=1——本路径未探测 hbcli/网络/凭证');
+        return;
+    }
     console.log(GUIDANCE.join('\n'));
     const bin = probeBin();
     if (!bin) {
-        console.log(`SKIP: 未安装 hbcli(候选 ${hbcliBinCandidates('hbcli').join(' / ')} 均不可执行)——npx gotry setup 可按官方脚本安装`);
+        console.log(`SKIP: 未安装 hbcli(候选 ${hbcliBinCandidates('hbcli').join(' / ')} 均不可执行)——npx @danceiny/gotry setup 可按官方脚本安装`);
         return;
     }
-    if (!await uatReachable()) {
+    if (!(await uatReachable())) {
         console.log(`SKIP: UAT(${UAT})不可达——全流程端到端在有网环境跑,离线降级面已由 hbcli-tests.ts(§7)覆盖`);
         return;
     }
+    // 隔离凭证面:全程不触碰用户默认 ~/.staicli
     const staicliHome = mkdtempSync(join(tmpdir(), 'gotry-hbcli-e2e-'));
     const stateRoot = mkdtempSync(join(tmpdir(), 'gotry-hbcli-e2e-state-'));
     process.env.STAICLI_HOME = staicliHome;
     const fallbackPath = join(import.meta.dirname, '..', '..', 'data', 'hotels_2026.json');
     try {
-        const set = spawnSync(bin, [
-            'auth',
-            'set-credentials',
-            '--app-key',
-            SANDBOX_APP_KEY,
-            '--app-secret',
-            SANDBOX_APP_SECRET
-        ], {
-            timeout: 30_000,
-            encoding: 'utf-8'
-        });
+        // 1) 沙箱账号写入隔离凭证面(hbcli auth set-credentials)
+        const set = spawnSync(bin, ['auth', 'set-credentials', '--app-key', SANDBOX_APP_KEY, '--app-secret', SANDBOX_APP_SECRET], { timeout: 30_000, encoding: 'utf-8' });
         assert.equal(set.status, 0, `auth set-credentials 应成功,实际 ${set.status}: ${set.stderr?.slice(0, 200)}`);
         console.log(`1. 沙箱账号写入隔离 STAICLI_HOME(${staicliHome.replace(tmpdir(), '$TMPDIR')})OK`);
-        const who = spawnSync(bin, [
-            'auth',
-            'whoami'
-        ], {
-            timeout: 30_000,
-            encoding: 'utf-8'
-        });
+        // 1b) whoami 自检:api_key.configured=true(配置面就位,尚未取票)
+        const who = spawnSync(bin, ['auth', 'whoami'], { timeout: 30_000, encoding: 'utf-8' });
         assert.equal(who.status, 0, 'whoami 应 exit 0');
         assert.match(who.stdout, /"configured": true/, 'whoami 应报 api_key.configured=true');
         console.log('1b. hbcli auth whoami 自检(api_key.configured=true)OK');
-        const dest = await listDestinations({
-            timeoutMs: 30_000
-        });
+        // 2) 能力层真实 spawn:目的地列表(通道真实性——UAT 参考数据可为空,通道必须真实)
+        const dest = await listDestinations({ timeoutMs: 30_000 });
         assert.equal(dest.via, 'hbcli-realtime', `destinations 应走实时通道,实际 ${dest.via}(${dest.error ?? ''})`);
         assert.equal(dest.exitCode, 0, 'destinations 应 exit 0');
         assert.match(dest.evidence, /\[实时API:hbcli@\d{4}-/, '证据链应带实时时间戳标注(L4 不变量)');
         assert.ok(dest.result !== null && typeof dest.result === 'object', '实时返回应可解析为 JSON');
         console.log(`2. 能力层实时通道(listDestinations → ${UAT})via=hbcli-realtime,证据链 OK`);
-        const hotels = await searchHotels({
-            destination: '深圳',
-            checkIn: '2026-09-18',
-            checkOut: '2026-09-20',
-            adults: 2
-        }, {
-            timeoutMs: 30_000,
-            fallbackPath
-        });
+        // 3) hotel-list 全链路:UAT 无目的地参考数据 → 业务层 404 → 降级诚实性
+        //    (真实失败不再是「工具坏了」,而是带上游原话的显式降级;issue #24 契约)
+        const hotels = await searchHotels({ destination: '深圳', checkIn: '2026-09-18', checkOut: '2026-09-20', adults: 2 }, { timeoutMs: 30_000, fallbackPath });
         if (hotels.via === 'hbcli-error') {
             assert.ok(hotels.error, '降级结果应携带上游原话原因');
             assert.match(hotels.summary, /降级/, 'summary 应显式声明降级(不伪装成实时)');
             assert.match(hotels.summary, /静态包/, '降级路径应指明静态包来源');
+            // 静态包含深圳块(data/hotels_2026.json)→ 降级应命中并标注「非实时」
             assert.ok(hotels.hotels !== null, '静态包深圳块应命中');
             assert.match(hotels.summary, /非实时/, '降级产物必须显式标注非实时(L4 反伪装红线)');
             console.log(`3. hotel-list 真实降级链(via=hbcli-error,原因:${String(hotels.error).slice(0, 60)}…;静态包命中+非实时标注)OK`);
-        } else {
+        }
+        else {
+            // UAT 后续补齐目的地数据时走此分支:实时返回必须带证据链
             assert.equal(hotels.via, 'hbcli-realtime');
             assert.match(hotels.evidence, /\[实时API:hbcli@\d{4}-/);
             console.log('3. hotel-list 实时返回(UAT 已有目的地数据)证据链 OK');
         }
-        const itp = await makeProductionInterpreter({
-            breakers: new Map()
-        })({
+        // 4) 效应解译层(ADR-18)真实通道:HBCLI_HOTEL_SEARCH 策略=永不重试+熔断在册;
+        //    独立 breakers Map,不污染产品单例
+        const itp = await makeProductionInterpreter({ breakers: new Map() })({
             effect: 'HBCLI_HOTEL_SEARCH',
-            params: {
-                destination: '深圳',
-                fallbackPath,
-                timeoutMs: 30_000
-            }
+            params: { destination: '深圳', fallbackPath, timeoutMs: 30_000 },
         });
         assert.equal(itp.trace.attempts, 1, `hbcli 策略永不重试,实际 attempts=${itp.trace.attempts}`);
         assert.equal(itp.trace.channel, 'cli');
@@ -129,50 +130,30 @@ async function main() {
         const viaAfter = itp.result.via;
         assert.ok(viaAfter === 'hbcli-error' || viaAfter === 'hbcli-realtime', `渠道 via 应保真,实际 ${viaAfter}`);
         console.log(`4. 效应解译层(attempts=1 永不重试,breaker=${itp.trace.breaker},via=${viaAfter})OK`);
+        // 5) 工具层端到端:gotry_hotel_search 经效应解译器跑完整链(隔离 stateRoot)
         const { apply } = await import('../src/index.js');
         const registered = [];
-        apply({
-            tools: {
-                register: (t)=>registered.push(t)
-            }
-        }, {
-            stateRoot,
-            timeoutMs: 30_000,
-            hbcliBin: 'hbcli',
-            sessionAccess: 'ask'
-        });
-        const tool = registered.find((t)=>t.name === 'gotry_hotel_search');
+        apply({ tools: { register: (t) => registered.push(t) } }, { stateRoot, timeoutMs: 30_000, hbcliBin: 'hbcli', sessionAccess: 'ask' });
+        const tool = registered.find(t => t.name === 'gotry_hotel_search');
         assert.ok(tool, 'gotry_hotel_search 应已注册');
-        const obs = await tool.execute({
-            destination: '深圳'
-        }, null);
+        const obs = await tool.execute({ destination: '深圳', checkIn: '2026-09-18', checkOut: '2026-09-20' }, null);
         assert.equal(obs.ok, true, '工具面应返回 ok 包络(永不抛错契约)');
         assert.ok(obs.via === 'hbcli-error' || obs.via === 'hbcli-realtime', `工具面 via 应与渠道一致,实际 ${obs.via}`);
         const ev = String(obs.evidence);
         if (obs.via === 'hbcli-error') {
             assert.match(ev, /静态包/, '降级时证据链应标注静态包(估算必须显式)');
-        } else {
+        }
+        else {
             assert.match(ev, /实时API:hbcli/, '实时时证据链应标注 hbcli 时间戳');
         }
         assert.ok(String(obs.summary).length > 0, 'summary 应存在');
         console.log(`5. 工具层端到端(gotry_hotel_search → 效应解译器 → ${UAT})via=${obs.via},evidence=${ev.slice(0, 46)}… OK`);
         console.log('HBCLI E2E TESTS: 5/5 OK(隔离凭证面/实时通道/降级诚实/解译策略/工具面全链)');
-    } finally{
+    }
+    finally {
         process.env.STAICLI_HOME = undefined;
-        rmSync(staicliHome, {
-            recursive: true,
-            force: true
-        });
-        rmSync(stateRoot, {
-            recursive: true,
-            force: true
-        });
+        rmSync(staicliHome, { recursive: true, force: true });
+        rmSync(stateRoot, { recursive: true, force: true });
     }
 }
-main().catch((e)=>{
-    console.error(e);
-    process.exitCode = 1;
-});
-
-
-//# sourceURL=ts/scripts/hbcli-e2e-tests.ts
+main().catch((e) => { console.error(e); process.exitCode = 1; });

package/dist/scripts/hbcli-live-optin-tests.js

@@ -0,0 +1,96 @@
+/**
+ * Offline supplier opt-in gate proof for issue #318.
+ *
+ * Spawn the real hbcli-e2e entrypoint with a discoverable fixture binary and
+ * a blocked-network/read-write trap. The default entrypoint must return before
+ * any probe, so the fixture and traps must all remain untouched.
+ *
+ * This test never enables GOTRY_HBCLI_LIVE and never calls a supplier endpoint.
+ */
+import assert from 'node:assert/strict';
+import { chmod, mkdir, mkdtemp, readFile, writeFile, rm } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+const root = join(import.meta.dirname, '..', '..');
+const e2e = join(root, 'ts', 'scripts', 'hbcli-e2e-tests.ts');
+const fixtureRoot = await mkdtemp(join(tmpdir(), 'gotry-issue-318-'));
+const fixtureHome = join(fixtureRoot, 'home');
+const fixtureBin = join(fixtureHome, '.local', 'bin', 'hbcli');
+const counters = join(fixtureRoot, 'counters');
+const launchCounter = join(counters, 'binary-launches');
+const networkCounter = join(counters, 'network-attempts');
+const credentialCounter = join(counters, 'credential-reads-writes');
+const trap = join(fixtureRoot, 'blocked-network-and-credential-trap.mjs');
+await mkdir(dirname(fixtureBin), { recursive: true });
+await mkdir(counters, { recursive: true });
+await writeFile(fixtureBin, `#!/bin/sh
+printf '1\\n' >> "$HBCLI_LAUNCH_COUNTER"
+printf 'fixture hbcli must not be started in offline mode\\n' >&2
+exit 97
+`);
+await chmod(fixtureBin, 0o755);
+await writeFile(trap, `import fs from 'node:fs'
+import { appendFileSync } from 'node:fs'
+import { syncBuiltinESMExports } from 'node:module'
+
+const networkCounter = ${JSON.stringify(networkCounter)}
+const credentialCounter = ${JSON.stringify(credentialCounter)}
+const credentialRoot = ${JSON.stringify(fixtureHome)}
+const realFetch = globalThis.fetch
+globalThis.fetch = async (...args) => {
+  appendFileSync(networkCounter, JSON.stringify(args[0]) + '\\n')
+  throw new Error('blocked network in issue #318 proof')
+}
+const isCredentialPath = (value) => String(value).startsWith(credentialRoot + '/.staicli')
+const realReadFileSync = fs.readFileSync
+fs.readFileSync = function (path, ...args) {
+  if (isCredentialPath(path)) appendFileSync(credentialCounter, 'read\\n')
+  return realReadFileSync.call(this, path, ...args)
+}
+const realWriteFileSync = fs.writeFileSync
+fs.writeFileSync = function (path, ...args) {
+  if (isCredentialPath(path)) appendFileSync(credentialCounter, 'write\\n')
+  return realWriteFileSync.call(this, path, ...args)
+}
+syncBuiltinESMExports()
+void realFetch
+`);
+try {
+    for (const optIn of [undefined, '0', 'true', 'yes']) {
+        const env = {
+            ...process.env,
+            HOME: fixtureHome,
+            PATH: `${dirname(fixtureBin)}:${process.env.PATH ?? ''}`,
+            NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --import=${trap}`.trim(),
+            HBCLI_LAUNCH_COUNTER: launchCounter,
+            STAICLI_HOME: join(fixtureHome, '.staicli'),
+        };
+        if (optIn === undefined)
+            delete env.GOTRY_HBCLI_LIVE;
+        else
+            env.GOTRY_HBCLI_LIVE = optIn;
+        const result = spawnSync('npx', ['--no-install', 'tsx', e2e], {
+            cwd: join(root, 'ts'), encoding: 'utf8', env,
+        });
+        assert.equal(result.status, 0, `offline entrypoint should exit 0 for ${String(optIn)}, stderr=${result.stderr}`);
+        assert.match(result.stdout, /SKIP: HotelByte UAT 已关闭/);
+        assert.match(result.stdout, /未探测 hbcli\/网络\/凭证/);
+    }
+    for (const [path, label] of [
+        [launchCounter, 'fixture binary launches'],
+        [networkCounter, 'network attempts'],
+        [credentialCounter, 'credential reads/writes'],
+    ]) {
+        let observed = '';
+        try {
+            observed = await readFile(path, 'utf8');
+        }
+        catch { /* absent means zero */ }
+        assert.equal(observed, '', `${label} must remain zero, observed=${observed}`);
+    }
+    console.log('HBCLI LIVE OPT-IN PROOF: real entrypoint + discoverable fixture + blocked network; unset/0/invalid => binary=0/network=0/credential=0');
+}
+finally {
+    await rm(fixtureRoot, { recursive: true, force: true });
+}

package/dist/scripts/hbcli-release-contract-tests.js

@@ -0,0 +1,122 @@
+/**
+ * #232 staicli release contract (test-only):
+ *   - verify a caller-supplied local npm tarball against the recorded bytes;
+ *   - inspect and execute the actual packaged hbcli entrypoint's safe help surface;
+ *   - prove the unsupported tenant selector is rejected by the actual parser;
+ *   - reject a one-byte tampered artifact before extraction/execution.
+ *
+ * This script never downloads, runs npm lifecycle scripts, reads credentials, or
+ * calls HotelByte/supplier endpoints. It does not classify supplier outcomes;
+ * those require recorded supplier response fixtures and the runtime adapter
+ * remains outside this preparation slice.
+ *
+ * Usage:
+ *   cd ts && npx tsx scripts/hbcli-release-contract-tests.ts /path/to/staicli-0.0.3.tgz
+ *   STAICLI_TARBALL=/path/to/staicli-0.0.3.tgz npx tsx scripts/hbcli-release-contract-tests.ts
+ */
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const manifestPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'fixtures', 'staicli-0.0.3.release-contract.json');
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+const tarballPath = process.argv[2] ?? process.env.STAICLI_TARBALL;
+if (!tarballPath) {
+    console.log('SKIP: no local staicli tarball supplied; pass argv[2] or STAICLI_TARBALL for artifact-byte verification');
+    process.exit(0);
+}
+assert.equal(manifest.schema_version, 'gotry_staicli_release_contract.v1');
+assert.ok(existsSync(tarballPath), `tarball must exist: ${tarballPath}`);
+function digest(algorithm, bytes) {
+    return createHash(algorithm).update(bytes).digest(algorithm === 'sha512' ? 'base64' : 'hex');
+}
+function sha256Text(text) {
+    return digest('sha256', Buffer.from(text));
+}
+function verifyTarball(path) {
+    const bytes = readFileSync(path);
+    const actualIntegrity = `sha512-${digest('sha512', bytes)}`;
+    assert.equal(actualIntegrity, manifest.artifact.integrity, 'tarball bytes must match the recorded npm integrity');
+    assert.equal(digest('sha256', bytes), manifest.artifact.sha256, 'tarball bytes must match the recorded SHA-256');
+    return bytes;
+}
+function runNode(entry, argv, home) {
+    mkdirSync(home, { recursive: true });
+    const result = spawnSync(process.execPath, [entry, ...argv], {
+        cwd: home,
+        env: {
+            HOME: home,
+            STAICLI_HOME: join(home, 'staicli'),
+            PATH: process.env.PATH ?? '',
+        },
+        encoding: 'utf8',
+        timeout: 10_000,
+        killSignal: 'SIGKILL',
+    });
+    return { status: result.status, signal: result.signal, stdout: result.stdout ?? '', stderr: result.stderr ?? '', error: result.error };
+}
+function assertRecordedCommand(name, entry, command, home) {
+    const result = runNode(entry, command.argv, home);
+    assert.equal(result.error, undefined, `${name} spawn failed: ${result.error?.message ?? 'unknown error'}`);
+    assert.equal(result.signal, null, `${name} exceeded the 10s subprocess bound`);
+    assert.equal(result.status, command.exit_code, `${name} exit code must match recorded artifact evidence`);
+    assert.equal(sha256Text(result.stdout), command.stdout_sha256, `${name} stdout must match recorded artifact evidence`);
+    assert.equal(sha256Text(result.stderr), command.stderr_sha256, `${name} stderr must match recorded artifact evidence`);
+    for (const line of command.required_lines)
+        assert.ok(result.stdout.includes(line), `${name} help must contain: ${line}`);
+}
+const workspace = mkdtempSync(join(tmpdir(), 'gotry-staicli-contract-'));
+const unpacked = join(workspace, 'unpacked');
+const tamperedPath = join(workspace, 'tampered.tgz');
+const isolatedHome = join(workspace, 'home');
+const extractedPackage = join(unpacked, 'package');
+mkdirSync(unpacked);
+try {
+    // 1. The recorded integrity is checked against the actual supplied tarball bytes.
+    const originalBytes = verifyTarball(tarballPath);
+    console.log(`1. tarball bytes verified (${manifest.artifact.package.name}@${manifest.artifact.package.version}, ${manifest.artifact.integrity})`);
+    // 2. A one-byte corruption must fail the same verification before execution.
+    const corrupted = Buffer.from(originalBytes);
+    corrupted[corrupted.length - 1] ^= 1;
+    writeFileSync(tamperedPath, corrupted);
+    assert.throws(() => verifyTarball(tamperedPath), /tarball bytes must match the recorded npm integrity/);
+    console.log('2. one-byte tarball corruption rejected by integrity verification');
+    // 3. Extract with tar only; npm is not invoked, and package scripts cannot run.
+    const extraction = spawnSync('tar', ['-xzf', tarballPath, '-C', unpacked], {
+        encoding: 'utf8',
+        timeout: 10_000,
+        killSignal: 'SIGKILL',
+    });
+    assert.equal(extraction.error, undefined, `tar spawn failed: ${extraction.error?.message ?? 'unknown error'}`);
+    assert.equal(extraction.signal, null, 'tar extraction exceeded the 10s subprocess bound');
+    assert.equal(extraction.status, 0, `tar extraction failed: ${extraction.stderr ?? ''}`);
+    const packageJson = JSON.parse(readFileSync(join(extractedPackage, 'package.json'), 'utf8'));
+    assert.equal(packageJson.name, manifest.artifact.package.name);
+    assert.equal(packageJson.version, manifest.artifact.package.version);
+    assert.equal(packageJson.main, manifest.artifact.package.main);
+    assert.deepEqual(packageJson.bin, manifest.artifact.package.bin);
+    const entry = join(extractedPackage, packageJson.bin.hbcli);
+    assert.ok(existsSync(entry), `recorded hbcli bin must exist: ${entry}`);
+    console.log(`3. packaged identity/bin verified (${packageJson.name}@${packageJson.version} -> ${packageJson.bin.hbcli})`);
+    // 4. Execute only safe help commands with a fresh HOME and STAICLI_HOME.
+    for (const [name, command] of Object.entries(manifest.safe_help)) {
+        assertRecordedCommand(name, entry, command, join(isolatedHome, name));
+        console.log(`4.${name}. actual packaged help surface verified (exit ${command.exit_code})`);
+    }
+    // 5. The actual Commander parser, not a copied schema, rejects the unsupported selector.
+    const selector = runNode(entry, manifest.unsupported_selector.argv, join(isolatedHome, 'selector'));
+    assert.equal(selector.error, undefined, `selector parser spawn failed: ${selector.error?.message ?? 'unknown error'}`);
+    assert.equal(selector.signal, null, 'selector parser exceeded the 10s subprocess bound');
+    assert.equal(selector.status, manifest.unsupported_selector.exit_code);
+    assert.equal(sha256Text(selector.stderr), manifest.unsupported_selector.stderr_sha256);
+    assert.ok(selector.stderr.includes(manifest.unsupported_selector.stderr_contains));
+    assert.equal(selector.stdout, '');
+    console.log('5. actual parser rejects --tenant-entity-id without entering a supplier action');
+}
+finally {
+    rmSync(workspace, { recursive: true, force: true });
+}
+console.log('HBCLI RELEASE CONTRACT TESTS: 5/5 OK (artifact bytes/help/parser/tamper; no supplier or credential access)');