@adhdev/ghostty-vt-node 1.0.78 → 1.0.82-rc.37

package/scripts/prebuilt-manifest.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// Per-platform prebuilt manifests: prebuilt/<triplet>/manifest.json records the
+// binding source digest, API level and build provenance the binary reports
+// about ITSELF (read from the compiled addon, never from the current sources)
+// plus the sha256 of every runtime file in the directory. `check` compares each
+// shipped triplet against the sources and toolchain pin in this checkout, so
+// editing the bridge/addon (or the zig pin) makes every prebuilt "pending
+// rebuild" until it is rebuilt on its own platform. It also validates, without
+// loading anything, that the directory holds its platform's runtime set in the
+// right native format (scripts/native-format.mjs), so release CI on Linux can
+// reject e.g. darwin files placed in the win32 directory.
+//
+//   node scripts/prebuilt-manifest.mjs write <dir>     # stamp a directory (loads its addon)
+//   node scripts/prebuilt-manifest.mjs emit [<from>]   # copy build/Release into the shipped
+//                                                      # triplet for this platform-arch + stamp
+//   node scripts/prebuilt-manifest.mjs check [--all-present]
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { PACKAGE_DIR, computeBindingDigest, pinnedGhosttyRevision, pinnedZigVersion } from './binding-digest.mjs';
+import { checkRuntimeSet, parseTriplet } from './native-format.mjs';
+
+export const PREBUILT_ROOT = join(PACKAGE_DIR, 'prebuilt');
+export const ADDON_FILE = 'ghostty_vt_node.node';
+export const MANIFEST_FILE = 'manifest.json';
+// 2: adds `release` and `provenance` (resolved ghostty source, toolchain).
+export const MANIFEST_SCHEMA = 2;
+// The addon plus its co-located runtime libs. Matches build-or-use-prebuilt.mjs.
+export const RUNTIME_FILE_PATTERN = /\.(node|dylib|so|so\.\d.*|dll)$/;
+// The committed prebuilt set (see .gitignore). One N-API binary per
+// platform-arch serves every Node ABI; the node137 name is only an address.
+export const SHIPPED_TRIPLETS = ['darwin-arm64-node137', 'linux-x64-node137', 'win32-x64-node137'];
+
+const requireNative = createRequire(import.meta.url);
+
+export function expectedApiLevel(packageDir = PACKAGE_DIR) {
+    const header = readFileSync(join(packageDir, 'src', 'ghostty_bridge.h'), 'utf8');
+    const match = header.match(/#define ADHDEV_GHOSTTY_API_LEVEL (\d+)/);
+    if (!match) throw new Error('src/ghostty_bridge.h does not define ADHDEV_GHOSTTY_API_LEVEL');
+    return Number(match[1]);
+}
+
+export function shippedTripletFor(platform = process.platform, arch = process.arch) {
+    return SHIPPED_TRIPLETS.find((name) => name.startsWith(`${platform}-${arch}-`)) ?? null;
+}
+
+const sha256File = (file) => createHash('sha256').update(readFileSync(file)).digest('hex');
+
+function runtimeFiles(dir) {
+    return readdirSync(dir).filter((name) => RUNTIME_FILE_PATTERN.test(name)).sort();
+}
+
+// Loads the exact addon in `dir` (no package-level fallback) and returns what
+// it reports about itself. Binaries predating getBindingInfo report level 1.
+export function readBinaryInfo(dir) {
+    const addon = requireNative(resolve(dir, ADDON_FILE));
+    if (typeof addon.getBindingInfo !== 'function') {
+        return { apiLevel: 1, sourceDigest: null, ghosttyRevision: null, napiVersion: null };
+    }
+    return addon.getBindingInfo();
+}
+
+export function writeManifest(dir) {
+    const info = readBinaryInfo(dir);
+    if (!info.sourceDigest) throw new Error(`${dir}: addon does not embed a binding source digest (api level ${info.apiLevel})`);
+    const files = {};
+    for (const name of runtimeFiles(dir)) {
+        const file = join(dir, name);
+        files[name] = { sha256: sha256File(file), size: statSync(file).size };
+    }
+    const manifest = {
+        schema: MANIFEST_SCHEMA,
+        platform: process.platform,
+        arch: process.arch,
+        apiLevel: info.apiLevel,
+        sourceDigest: info.sourceDigest,
+        ghosttyRevision: info.ghosttyRevision,
+        napiVersion: info.napiVersion,
+        builtWithNode: process.version,
+        release: info.releaseEligible === true,
+        provenance: {
+            problems: info.provenanceProblems ?? ['no-build-provenance'],
+            ghosttySourceRevision: info.ghosttySourceRevision ?? null,
+            ghosttySourceClean: info.ghosttySourceClean ?? false,
+            zigVersion: info.zigVersion ?? null,
+            cCompiler: info.cCompiler ?? null,
+            cxxCompiler: info.cxxCompiler ?? null,
+            buildType: info.buildType ?? null,
+        },
+        files,
+    };
+    writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+    return manifest;
+}
+
+const LINUX_SONAME = 'libghostty-vt.so.0';
+const LINUX_VERSIONED = /^libghostty-vt\.so\.0\.\d+\.\d+$/;
+
+export function emitPrebuilt(fromDir = join(PACKAGE_DIR, 'build', 'Release')) {
+    const triplet = shippedTripletFor() ?? `${process.platform}-${process.arch}-node${process.versions.modules}`;
+    const target = join(PREBUILT_ROOT, triplet);
+    mkdirSync(target, { recursive: true });
+    // Replace the whole runtime set: a leftover library from the previous build
+    // (e.g. the Linux SONAME file, which the build output may not contain) would
+    // otherwise be shipped next to an addon built against a different one.
+    for (const name of runtimeFiles(target)) rmSync(join(target, name));
+    for (const name of runtimeFiles(fromDir)) copyFileSync(join(fromDir, name), join(target, name));
+    const versioned = readdirSync(target).find((name) => LINUX_VERSIONED.test(name));
+    if (versioned && !existsSync(join(target, LINUX_SONAME))) copyFileSync(join(target, versioned), join(target, LINUX_SONAME));
+    const manifest = writeManifest(target);
+    return { triplet, target, manifest };
+}
+
+// Status of one prebuilt directory against the current sources:
+//   ok              manifest matches the sources and every file hash matches
+//   pending-rebuild built from other sources/toolchain, or stamped with an older
+//                   manifest schema (or never stamped): rebuild it on its platform
+//   wrong-platform  the manifest or the files are for another platform/arch
+//   invalid-runtime the platform's mandatory runtime set is incomplete or a file
+//                   is not a shared library of the right format
+//   corrupt         files differ from what the manifest recorded
+//   non-release     built with ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD (unverified
+//                   ghostty source or toolchain): never publishable
+export function checkTriplet(triplet, expected, root = PREBUILT_ROOT) {
+    const dir = join(root, triplet);
+    if (!existsSync(join(dir, ADDON_FILE))) return { triplet, status: 'missing', detail: `no ${ADDON_FILE}` };
+    const manifestPath = join(dir, MANIFEST_FILE);
+    if (!existsSync(manifestPath)) return { triplet, status: 'pending-rebuild', detail: 'no manifest.json (binary predates the current binding sources)' };
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch (error) {
+        return { triplet, status: 'corrupt', detail: `unreadable manifest.json: ${error.message}` };
+    }
+    const target = parseTriplet(triplet);
+    if (!target) return { triplet, status: 'wrong-platform', detail: 'directory name is not <platform>-<arch>-node<abi>' };
+    if (manifest.platform !== target.platform || manifest.arch !== target.arch) {
+        return { triplet, status: 'wrong-platform', detail: `manifest is for ${manifest.platform}-${manifest.arch}` };
+    }
+    const present = runtimeFiles(dir);
+    const runtimeProblems = checkRuntimeSet(dir, target.platform, target.arch, present);
+    if (runtimeProblems.length) return { triplet, status: 'invalid-runtime', detail: runtimeProblems.join('; ') };
+
+    const problems = [];
+    const recorded = Object.keys(manifest.files ?? {}).sort();
+    for (const name of recorded) {
+        if (!present.includes(name)) problems.push(`${name} missing`);
+        else if (sha256File(join(dir, name)) !== manifest.files[name].sha256) problems.push(`${name} hash differs from manifest`);
+    }
+    // An unrecorded file is accepted only as a byte-identical alias of a recorded
+    // one: release CI materializes the Linux SONAME copy after artifacts drop
+    // symlinks (ensure-prebuilt-sonames.mjs).
+    const recordedHashes = new Set(recorded.map((name) => manifest.files[name].sha256));
+    for (const name of present) {
+        if (!recorded.includes(name) && !recordedHashes.has(sha256File(join(dir, name)))) problems.push(`${name} not in manifest`);
+    }
+    if (!recorded.includes(ADDON_FILE)) problems.push(`manifest does not record ${ADDON_FILE}`);
+    // The addon embeds its digest as a string; a manifest claiming another one
+    // was not stamped from this binary.
+    else if (typeof manifest.sourceDigest === 'string' && manifest.sourceDigest
+        && !readFileSync(join(dir, ADDON_FILE)).includes(Buffer.from(manifest.sourceDigest, 'latin1'))) {
+        problems.push(`${ADDON_FILE} does not embed the manifest sourceDigest`);
+    }
+    if (problems.length) return { triplet, status: 'corrupt', detail: problems.join('; ') };
+
+    if (manifest.schema !== MANIFEST_SCHEMA) {
+        return { triplet, status: 'pending-rebuild', detail: `manifest schema ${manifest.schema} predates build provenance (want ${MANIFEST_SCHEMA})` };
+    }
+    const stale = [];
+    if (manifest.sourceDigest !== expected.sourceDigest) stale.push(`sourceDigest ${String(manifest.sourceDigest).slice(0, 12)} != ${expected.sourceDigest.slice(0, 12)}`);
+    if (manifest.apiLevel !== expected.apiLevel) stale.push(`apiLevel ${manifest.apiLevel} != ${expected.apiLevel}`);
+    if (manifest.ghosttyRevision !== expected.ghosttyRevision) stale.push(`ghosttyRevision ${manifest.ghosttyRevision} != ${expected.ghosttyRevision}`);
+    const provenance = manifest.provenance ?? {};
+    if (provenance.zigVersion !== expected.zigVersion) stale.push(`zig ${provenance.zigVersion} != ${expected.zigVersion} (toolchain.json)`);
+    if (stale.length) return { triplet, status: 'pending-rebuild', detail: stale.join('; ') };
+
+    const unverified = [];
+    if (manifest.release !== true) unverified.push('stamped non-release');
+    if (Array.isArray(provenance.problems) && provenance.problems.length) unverified.push(`problems: ${provenance.problems.join(', ')}`);
+    if (provenance.ghosttySourceRevision !== expected.ghosttyRevision) unverified.push(`built ghostty ${provenance.ghosttySourceRevision} != pin`);
+    if (provenance.ghosttySourceClean !== true) unverified.push('ghostty source not clean');
+    if (unverified.length) return { triplet, status: 'non-release', detail: unverified.join('; ') };
+    return { triplet, status: 'ok', detail: `digest ${manifest.sourceDigest.slice(0, 12)}, api ${manifest.apiLevel}, zig ${provenance.zigVersion}, ${provenance.cxxCompiler}, node ${manifest.builtWithNode}` };
+}
+
+export function currentExpectation(packageDir = PACKAGE_DIR) {
+    return {
+        sourceDigest: computeBindingDigest(packageDir),
+        apiLevel: expectedApiLevel(packageDir),
+        ghosttyRevision: pinnedGhosttyRevision(packageDir),
+        zigVersion: pinnedZigVersion(packageDir),
+    };
+}
+
+export function checkManifests({ allPresent = false, root = PREBUILT_ROOT } = {}) {
+    const expected = currentExpectation();
+    const triplets = new Set(SHIPPED_TRIPLETS);
+    if (allPresent && existsSync(root)) {
+        for (const name of readdirSync(root)) {
+            if (existsSync(join(root, name, ADDON_FILE))) triplets.add(name);
+        }
+    }
+    return { expected, results: [...triplets].sort().map((triplet) => checkTriplet(triplet, expected, root)) };
+}
+
+export function printManifestReport({ expected, results }, log = console.log) {
+    log(`[ghostty-vt] binding source digest ${expected.sourceDigest} (api ${expected.apiLevel}, ghostty ${expected.ghosttyRevision.slice(0, 12)}, zig ${expected.zigVersion})`);
+    for (const r of results) log(`  ${r.status === 'ok' ? '✓' : '✗'} ${r.triplet.padEnd(22)} ${r.status.padEnd(16)} ${r.detail}`);
+    const bad = results.filter((r) => r.status !== 'ok');
+    log(`[ghostty-vt] ${results.length - bad.length}/${results.length} prebuilts match the binding sources`);
+    return bad.length === 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+    const [command, arg] = process.argv.slice(2);
+    if (command === 'write' && arg) {
+        const manifest = writeManifest(resolve(arg));
+        console.log(`[ghostty-vt] wrote ${join(arg, MANIFEST_FILE)} (digest ${manifest.sourceDigest}, api ${manifest.apiLevel})`);
+    } else if (command === 'emit') {
+        const { target, manifest } = emitPrebuilt(arg ? resolve(arg) : undefined);
+        console.log(`[ghostty-vt] emitted prebuilt → ${target} (digest ${manifest.sourceDigest}, api ${manifest.apiLevel})`);
+    } else if (command === 'check') {
+        if (!printManifestReport(checkManifests({ allPresent: process.argv.includes('--all-present') }))) process.exit(1);
+    } else {
+        console.error('usage: prebuilt-manifest.mjs write <dir> | emit [<from>] | check [--all-present]');
+        process.exit(2);
+    }
+}

package/scripts/probe-build-provenance.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+// Scripted probe for the build-provenance guarantees in CMakeLists.txt. Needs a
+// configured cmake-js build of this package (e.g. a neutral /tmp/gvn copy after
+// `cmake-js rebuild`) plus cmake, git, network access and the pinned zig; it is
+// not part of the unit tests because it compiles twice from empty caches.
+// Each probe mutates the build tree and restores it; the final state is a
+// fresh, release-eligible build. Run it with exclusive use of the build tree.
+//
+//   node scripts/probe-build-provenance.mjs <package copy dir>   # uses <dir>/build
+//
+// Probes:
+//   stale-runtime-relink   same-size garbage in the installed runtime + addon
+//                          relink: the shipped runtime must be the rebuilt one
+//   stale-runtime-idle     same, nothing to relink: the runtime is still refreshed
+//   ambient-cache-poison   ZIG_GLOBAL_CACHE_DIR / ZIG_LOCAL_CACHE_DIR pointing at
+//                          a poisoned package cache are never read or written
+//   source-modified        a ghostty source edit after configure fails the build
+//   dev-override           ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=ON alone => release=0
+//   poison-is-live         control: the poisoned PRIVATE caches break a build
+//                          that keeps them (dev override), so the poison bites
+//   zig-strict             "0.15.2!" / "0.15 .2" / two lines refused, " X\r\n" accepted
+//   clean-fails-closed     a cache clean that leaves anything behind (simulated
+//                          with a no-op fs.rmSync) fails the release configure
+//   reconfigure-clears     a release configure empties the private caches/prefix,
+//                          including planted trailing-dot (`._.`) entries that
+//                          CMake's file(REMOVE_RECURSE) cannot delete on Windows
+//   private-cache-poison   ...so the poisoned package/artifact caches are never
+//                          used: the release rebuild yields the baseline runtime
+//   source-override        FETCHCONTENT_SOURCE_DIR_GHOSTTY => refused
+import { spawnSync } from 'node:child_process';
+import { createHash, randomFillSync } from 'node:crypto';
+import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { pinnedZigVersion } from './binding-digest.mjs';
+import { checkNativeFile } from './native-format.mjs';
+
+// Canonical path: the build embeds source paths (e.g. /tmp vs /private/tmp on
+// macOS), so every configure must see the same spelling for runtimes to match.
+const dir = process.argv[2] && existsSync(process.argv[2]) ? realpathSync(resolve(process.argv[2])) : null;
+if (!dir || !existsSync(join(dir, 'build', 'CMakeCache.txt'))) {
+    console.error('usage: probe-build-provenance.mjs <dir containing a configured cmake-js build/>');
+    process.exit(2);
+}
+const build = join(dir, 'build');
+const source = join(build, '_deps', 'ghostty-src');
+const zigDir = join(build, 'ghostty-zig');
+const globalCache = join(zigDir, 'global-cache');
+const localCache = join(zigDir, 'local-cache');
+const cache = readFileSync(join(build, 'CMakeCache.txt'), 'utf8');
+const realZig = /^ZIG_EXECUTABLE:FILEPATH=(.*)$/m.exec(cache)?.[1];
+const isWin = process.platform === 'win32';
+const libName = process.platform === 'darwin' ? 'libghostty-vt.0.1.0.dylib' : isWin ? 'ghostty-vt.dll' : 'libghostty-vt.so.0.1.0';
+const installedLib = join(zigDir, 'prefix', isWin ? 'bin' : 'lib', libName);
+const releaseLib = join(build, 'Release', libName);
+const sha = (file) => (existsSync(file) ? createHash('sha256').update(readFileSync(file)).digest('hex') : null);
+const run = (cmd, args, env = {}) => {
+    const result = spawnSync(cmd, args, { cwd: dir, encoding: 'utf8', windowsHide: true, env: { ...process.env, ...env }, maxBuffer: 1 << 28 });
+    return { status: result.status, out: `${result.stdout ?? ''}${result.stderr ?? ''}` };
+};
+const configure = (defs = [], env = {}) => run('cmake', [build, ...defs.map((d) => `-D${d}`)], env);
+const compile = (env = {}) => run('cmake', ['--build', build, '--config', 'Release'], env);
+// Two fresh zig builds are not byte-identical: the debug map / debug info names
+// the per-build local-cache object directories and their mtimes, and the image
+// id (LC_UUID, build-id, PDB GUID) and code signature follow from that. The
+// LOADED code and data must be identical, so runtimes from different fresh
+// builds are compared by a digest of their loaded sections:
+//   Mach-O  every section outside __LINKEDIT (zerofill excluded)
+//   ELF     SHF_ALLOC sections except NOBITS and notes (build-id)
+//   PE      every section, with debug-directory and export timestamps / debug
+//           payloads zeroed
+const loadedDigest = (file) => {
+    if (!existsSync(file)) return null;
+    const b = Buffer.from(readFileSync(file));
+    const hash = createHash('sha256');
+    if (b.readUInt32LE(0) === 0xfeedfacf) {
+        let at = 32;
+        for (let i = 0; i < b.readUInt32LE(16); i++) {
+            const cmd = b.readUInt32LE(at);
+            if (cmd === 0x19 && b.toString('latin1', at + 8, at + 24).replace(/\0.*$/s, '') !== '__LINKEDIT') {
+                for (let k = 0; k < b.readUInt32LE(at + 64); k++) {
+                    const sect = at + 72 + k * 80;
+                    const type = b.readUInt32LE(sect + 64) & 0xff;
+                    if (type === 0x01 || type === 0x0c || type === 0x12) continue; // zerofill kinds
+                    const size = Number(b.readBigUInt64LE(sect + 40));
+                    const off = b.readUInt32LE(sect + 48);
+                    hash.update(b.subarray(sect, sect + 32)).update(b.subarray(off, off + size));
+                }
+            }
+            at += b.readUInt32LE(at + 4);
+        }
+    } else if (b.readUInt32BE(0) === 0x7f454c46) {
+        const shoff = Number(b.readBigUInt64LE(40));
+        for (let i = 0; i < b.readUInt16LE(60); i++) {
+            const sh = shoff + i * 64;
+            const type = b.readUInt32LE(sh + 4);
+            const flags = Number(b.readBigUInt64LE(sh + 8));
+            if (!(flags & 2) || type === 8 || type === 7) continue;
+            const off = Number(b.readBigUInt64LE(sh + 24));
+            hash.update(b.subarray(sh, sh + 64)).update(b.subarray(off, off + Number(b.readBigUInt64LE(sh + 32))));
+        }
+    } else if (b[0] === 0x4d && b[1] === 0x5a) {
+        const pe = b.readUInt32LE(0x3c);
+        const opt = pe + 24;
+        const sectionTable = opt + b.readUInt16LE(pe + 20);
+        const sections = Array.from({ length: b.readUInt16LE(pe + 6) }, (_, i) => {
+            const sh = sectionTable + i * 40;
+            return { sh, va: b.readUInt32LE(sh + 12), vsize: b.readUInt32LE(sh + 8), raw: b.readUInt32LE(sh + 20), rawSize: b.readUInt32LE(sh + 16) };
+        });
+        const fileOffset = (rva) => { const s = sections.find((x) => rva >= x.va && rva < x.va + Math.max(x.vsize, x.rawSize)); return s ? s.raw + rva - s.va : -1; };
+        const exportDir = fileOffset(b.readUInt32LE(opt + 112));
+        if (b.readUInt32LE(opt + 116) && exportDir >= 0) b.fill(0, exportDir + 4, exportDir + 8);
+        const debugDir = fileOffset(b.readUInt32LE(opt + 112 + 6 * 8));
+        const debugSize = b.readUInt32LE(opt + 116 + 6 * 8);
+        for (let d = 0; debugDir >= 0 && d + 28 <= debugSize; d += 28) {
+            const entry = debugDir + d;
+            b.fill(0, entry + 4, entry + 8);
+            const dataSize = b.readUInt32LE(entry + 16);
+            const dataPtr = b.readUInt32LE(entry + 24);
+            if (dataPtr && dataPtr + dataSize <= b.length) b.fill(0, dataPtr, dataPtr + dataSize);
+        }
+        for (const s of sections) hash.update(b.subarray(s.sh, s.sh + 40)).update(b.subarray(s.raw, s.raw + s.rawSize));
+    } else {
+        return null;
+    }
+    return hash.digest('hex');
+};
+const platformArch = [process.platform, process.arch];
+const releaseFlag = (out) => /provenance: .* release=(\d)/.exec(out)?.[1] ?? null;
+const walk = (root) => (existsSync(root) ? readdirSync(root, { recursive: true, withFileTypes: true }) : [])
+    .filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath ?? entry.path, entry.name));
+// path:size:mtime of every file: shows a tree was neither modified nor added to.
+const snapshot = (root) => JSON.stringify(walk(root).sort().map((file) => { const st = statSync(file); return `${file}:${st.size}:${st.mtimeMs}`; }));
+
+const results = [];
+const probe = (name, ok, detail) => { results.push(ok); console.log(`  ${ok ? '✓' : '✗'} ${name}: ${detail}`); };
+const plantGarbage = () => {
+    const garbage = Buffer.alloc(statSync(installedLib).size);
+    randomFillSync(garbage);
+    writeFileSync(installedLib, garbage);
+    return sha(installedLib);
+};
+// Make every Zig source in a package cache fail to compile and every cached
+// libghostty-vt artifact garbage, so any use of the poisoned state is visible.
+const POISON = '\ncomptime { @compileError("adhdev probe: poisoned zig package cache"); }\n';
+const poisonCaches = (globalRoot, localRoot) => {
+    let sources = 0;
+    let artifacts = 0;
+    for (const file of walk(join(globalRoot, 'p'))) {
+        if (file.endsWith('.zig')) { appendFileSync(file, POISON); sources++; }
+    }
+    for (const file of walk(localRoot)) {
+        if (/ghostty-vt/.test(file) && /\.(dylib|so[.\d]*|dll|lib|a)$/.test(file)) {
+            const garbage = Buffer.alloc(statSync(file).size);
+            randomFillSync(garbage);
+            writeFileSync(file, garbage);
+            artifacts++;
+        }
+    }
+    return { sources, artifacts };
+};
+
+// Baseline: a fresh release configure + build (empty private caches).
+const baseline = configure(['ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=OFF', `ZIG_EXECUTABLE=${realZig}`]);
+let built = baseline.status === 0 ? compile() : baseline;
+if (built.status !== 0 || releaseFlag(baseline.out) !== '1') { console.error(`baseline release build failed:\n${built.out.slice(-2000)}`); process.exit(1); }
+const good = sha(installedLib);
+const goodLoaded = loadedDigest(installedLib);
+console.log(`[probe] baseline runtime ${good?.slice(0, 16)} (loaded sections ${goodLoaded?.slice(0, 16)}, ${libName})`);
+
+let planted = plantGarbage();
+rmSync(join(build, 'Release', 'ghostty_vt_node.node'), { force: true });
+built = compile();
+probe('stale-runtime-relink', built.status === 0 && sha(installedLib) === good && sha(releaseLib) === good,
+    `planted ${planted.slice(0, 16)} -> installed ${sha(installedLib)?.slice(0, 16)}, Release ${sha(releaseLib)?.slice(0, 16)}`);
+
+planted = plantGarbage();
+built = compile();
+probe('stale-runtime-idle', built.status === 0 && sha(installedLib) === good, `planted ${planted.slice(0, 16)} -> installed ${sha(installedLib)?.slice(0, 16)}`);
+
+const ambient = mkdtempSync(join(tmpdir(), 'ghostty-ambient-zig-'));
+try {
+    // Ambient caches: a poisoned copy of this build's own package cache.
+    const ambientGlobal = join(ambient, 'global');
+    const ambientLocal = join(ambient, 'local');
+    cpSync(join(globalCache, 'p'), join(ambientGlobal, 'p'), { recursive: true });
+    mkdirSync(ambientLocal, { recursive: true });
+    const ambientPoison = poisonCaches(ambientGlobal, ambientLocal);
+    const ambientEnv = { ZIG_GLOBAL_CACHE_DIR: ambientGlobal, ZIG_LOCAL_CACHE_DIR: ambientLocal };
+    let before = snapshot(ambient);
+    rmSync(join(build, 'Release', 'ghostty_vt_node.node'), { force: true });
+    built = compile(ambientEnv);
+    probe('ambient-cache-poison', built.status === 0 && sha(installedLib) === good && snapshot(ambient) === before,
+        `${ambientPoison.sources} poisoned package sources in ZIG_GLOBAL_CACHE_DIR; build exit ${built.status}, runtime ${sha(installedLib)?.slice(0, 16)}, ambient caches ${snapshot(ambient) === before ? 'untouched' : 'CHANGED'}`);
+
+    try {
+        appendFileSync(join(source, 'README.md'), 'probe\n');
+        built = compile();
+        probe('source-modified', built.status !== 0 && /ghostty source tree changed since configure/.test(built.out), `build exit ${built.status}`);
+    } finally {
+        run('git', ['-C', source, 'checkout', '--', 'README.md']);
+    }
+
+    // Poison this build's PRIVATE caches. A configure that keeps them (dev
+    // override) must then fail to build: proof that the poison would be used.
+    const privatePoison = poisonCaches(globalCache, localCache);
+    let configured = configure(['ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=ON']);
+    probe('dev-override', configured.status === 0 && releaseFlag(configured.out) === '0' && /unverified-dev-build/.test(configured.out), `release=${releaseFlag(configured.out)}`);
+    built = compile();
+    probe('poison-is-live', built.status !== 0 && /poisoned zig package cache/.test(built.out),
+        `${privatePoison.sources} sources / ${privatePoison.artifacts} artifacts poisoned in the private caches; kept caches => build exit ${built.status}`);
+
+    // The fake zig prints EXACT bytes on every platform: a node script copies a
+    // data file to stdout, behind a shell (POSIX) or .cmd (Windows) wrapper. A
+    // cmd.exe `set /p` stub cannot emit a CR/LF or leading whitespace verbatim.
+    const fakeDir = mkdtempSync(join(tmpdir(), 'ghostty-fake-zig-'));
+    try {
+        const fakeOutput = join(fakeDir, 'version-output.txt');
+        const fakeScript = join(fakeDir, 'fake-zig.cjs');
+        writeFileSync(fakeScript, `process.stdout.write(require('node:fs').readFileSync(${JSON.stringify(fakeOutput)}));\n`);
+        const fake = join(fakeDir, isWin ? 'zig.cmd' : 'zig');
+        writeFileSync(fake, isWin
+            ? `@"${process.execPath}" "${fakeScript}" %*\r\n`
+            : `#!/bin/sh\nexec '${process.execPath.replace(/'/g, "'\\''")}' '${fakeScript.replace(/'/g, "'\\''")}' "$@"\n`);
+        chmodSync(fake, 0o755);
+        const pin = pinnedZigVersion();
+        for (const [output, accept] of [[`${pin}!`, false], [pin.replace(/\.(\d+)$/, ' .$1'), false], [`${pin}\nextra`, false], [` ${pin}\r\n`, true]]) {
+            writeFileSync(fakeOutput, output);
+            configured = configure(['ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=OFF', `ZIG_EXECUTABLE=${fake}`]);
+            const accepted = configured.status === 0 && releaseFlag(configured.out) === '1';
+            probe(`zig-strict ${JSON.stringify(output)}`, accepted === accept, accept ? 'accepted' : `refused (exit ${configured.status})`);
+        }
+    } finally {
+        rmSync(fakeDir, { recursive: true, force: true });
+    }
+
+    // Plant names Win32 normalizes away (zig extracts such `._.` AppleDouble
+    // files from some packages); \\?\ keeps the trailing dot on Windows.
+    const raw = (file) => (isWin ? `\\\\?\\${file}` : file);
+    mkdirSync(join(globalCache, 'p', 'adhdev-probe'), { recursive: true });
+    writeFileSync(raw(join(globalCache, 'p', 'adhdev-probe', '._.')), 'AppleDouble');
+    writeFileSync(raw(join(localCache, 'stale.')), 'x');
+
+    // A clean that leaves the caches in place must stop the release configure.
+    const mockDir = mkdtempSync(join(tmpdir(), 'ghostty-rm-mock-'));
+    try {
+        const mock = join(mockDir, 'rm-noop.cjs');
+        writeFileSync(mock, "require('node:fs').rmSync = () => {};\n");
+        configured = configure(['ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=OFF', `ZIG_EXECUTABLE=${realZig}`], { NODE_OPTIONS: `--require ${JSON.stringify(mock)}` });
+        const kept = walk(globalCache).length + walk(localCache).length;
+        probe('clean-fails-closed', configured.status !== 0 && /could not empty the private zig caches/.test(configured.out) && kept > 0,
+            `configure exit ${configured.status}; ${kept} planted cache files left in place`);
+    } finally {
+        rmSync(mockDir, { recursive: true, force: true });
+    }
+
+    // Release configure with the real zig and the ambient poison still in the
+    // environment: the private caches and prefix are emptied, then rebuilt
+    // from freshly fetched packages.
+    configured = configure(['ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=OFF', `ZIG_EXECUTABLE=${realZig}`], ambientEnv);
+    const leftovers = walk(globalCache).length + walk(localCache).length;
+    probe('reconfigure-clears', configured.status === 0 && releaseFlag(configured.out) === '1' && leftovers === 0 && !existsSync(installedLib),
+        `release=${releaseFlag(configured.out)}, ${leftovers} files left in the private caches (incl. planted ._. / trailing-dot), runtime ${existsSync(installedLib) ? 'still present' : 'deleted'}`);
+    before = snapshot(ambient);
+    built = compile(ambientEnv);
+    // A fresh build: equal loaded sections to the baseline (bytes differ only in
+    // per-build debug metadata), a well-formed library, shipped as built.
+    const formatProblems = existsSync(installedLib) ? checkNativeFile(libName, readFileSync(installedLib), ...platformArch) : ['missing'];
+    probe('private-cache-poison', built.status === 0 && loadedDigest(installedLib) === goodLoaded && formatProblems.length === 0
+        && sha(releaseLib) === sha(installedLib) && snapshot(ambient) === before,
+        `fresh release build exit ${built.status}, loaded sections ${loadedDigest(installedLib)?.slice(0, 16)} (baseline ${goodLoaded?.slice(0, 16)}; raw ${sha(installedLib)?.slice(0, 16)} vs ${good?.slice(0, 16)}), format ${formatProblems.length ? formatProblems.join('; ') : 'ok'}, ambient ${snapshot(ambient) === before ? 'untouched' : 'CHANGED'}`);
+} finally {
+    rmSync(ambient, { recursive: true, force: true });
+    run('git', ['-C', source, 'checkout', '--', '.']);
+}
+
+const probeBuild = mkdtempSync(join(tmpdir(), 'ghostty-override-'));
+try {
+    const override = run('cmake', ['-S', dir, '-B', probeBuild, `-DFETCHCONTENT_SOURCE_DIR_GHOSTTY=${source}`, `-DZIG_EXECUTABLE=${realZig}`]);
+    probe('source-override', override.status !== 0 && /ghostty-source-override/.test(override.out), `configure exit ${override.status}`);
+} finally {
+    rmSync(probeBuild, { recursive: true, force: true });
+}
+
+const failed = results.filter((ok) => !ok).length;
+console.log(`[probe] ${results.length - failed}/${results.length} provenance probes passed`);
+if (failed) process.exit(1);

package/scripts/verify-prebuilt.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Exercise the EXACT addon in a directory — require()d by path, so neither the
+// package loader's build/Release preference nor its same-platform fallback can
+// substitute a different binary — and fail unless it is built from the binding
+// sources in this checkout, by the pinned toolchain from a verified ghostty
+// checkout (release eligible), and its viewport API behaves. Loading alone
+// proves nothing about the API: a stale binary loads fine. Every native file in the
+// directory is also byte-scanned for embedded home-directory paths.
+//
+//   node scripts/verify-prebuilt.mjs <dir>     # e.g. prebuilt/darwin-arm64-node137
+import { createRequire } from 'node:module';
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { computeBindingDigest, pinnedGhosttyRevision, pinnedZigVersion } from './binding-digest.mjs';
+import { scanHostPaths } from './host-path-scan.mjs';
+import { checkNativeFile } from './native-format.mjs';
+import { ADDON_FILE, RUNTIME_FILE_PATTERN, expectedApiLevel } from './prebuilt-manifest.mjs';
+
+const requireNative = createRequire(import.meta.url);
+
+function expect(checks, name, actual, expected) {
+    const ok = JSON.stringify(actual) === JSON.stringify(expected);
+    checks.push({ name, ok, detail: ok ? JSON.stringify(actual) : `got ${JSON.stringify(actual)}, want ${JSON.stringify(expected)}` });
+    return ok;
+}
+
+function scanChecks(dir) {
+    return scanHostPaths([dir]).map(({ file, hits }) => ({
+        name: `no host paths in ${basename(file)}`,
+        ok: hits.length === 0,
+        detail: hits.length === 0
+            ? 'clean (ASCII + UTF-16LE)'
+            : hits.slice(0, 5).map((hit) => `0x${hit.offset.toString(16)} ${hit.encoding} ${JSON.stringify(hit.prefix)}`).join('; ') + (hits.length > 5 ? ` … +${hits.length - 5}` : ''),
+    }));
+}
+
+export function verifyPrebuilt(dir, { hostPathScan = true } = {}) {
+    // Scanned before loading: a binary that leaks paths fails even if it cannot load.
+    const checks = hostPathScan ? scanChecks(dir) : [];
+    for (const name of readdirSync(dir).filter((entry) => RUNTIME_FILE_PATTERN.test(entry)).sort()) {
+        const problems = checkNativeFile(name, readFileSync(resolve(dir, name)), process.platform, process.arch);
+        checks.push({ name: `native format of ${name}`, ok: problems.length === 0, detail: problems.length ? problems.join('; ') : `${process.platform}-${process.arch} shared library` });
+    }
+    const file = resolve(dir, ADDON_FILE);
+    let addon;
+    try {
+        addon = requireNative(file);
+    } catch (error) {
+        checks.push({ name: 'load', ok: false, detail: error.message });
+        return { file, checks };
+    }
+    if (typeof addon.getBindingInfo !== 'function') {
+        checks.push({ name: 'getBindingInfo', ok: false, detail: 'missing: binary predates API level 2 (rebuild it)' });
+        return { file, checks };
+    }
+    const info = addon.getBindingInfo();
+    expect(checks, 'apiLevel', info.apiLevel, expectedApiLevel());
+    expect(checks, 'sourceDigest matches sources', info.sourceDigest, computeBindingDigest());
+    expect(checks, 'ghosttyRevision is the pin', info.ghosttyRevision, pinnedGhosttyRevision());
+    expect(checks, 'built ghostty checkout is the pin', info.ghosttySourceRevision, pinnedGhosttyRevision());
+    expect(checks, 'built ghostty checkout is clean', info.ghosttySourceClean, true);
+    expect(checks, 'zig is the toolchain.json pin', info.zigVersion, pinnedZigVersion());
+    expect(checks, 'release eligible (no provenance problems)', [info.releaseEligible, info.provenanceProblems], [true, []]);
+
+    const terminal = addon.createTerminal({ cols: 12, rows: 4, scrollback: 100000 });
+    try {
+        for (const name of ['getViewport', 'readRow', 'scrollViewport']) {
+            expect(checks, `${name} present`, typeof terminal[name], 'function');
+        }
+        if (checks.some((check) => !check.ok)) return { file, info, checks };
+
+        terminal.write('old\r\n'.repeat(40) + '> FINAL');
+        const view = terminal.getViewport({ includeRows: 'all', cells: true });
+        expect(checks, 'scrollbar', view.scrollbar, { total: 41, offset: 37, len: 4 });
+        expect(checks, 'cursor (active)', [view.cursorRow, view.cursorCol, view.cursorViewportRow], [3, 7, 3]);
+        expect(checks, 'cursor row text', view.lines[view.cursorRow].text, '> FINAL');
+        terminal.write('Z');
+        const marked = terminal.getViewport({ includeRows: 'cursor' });
+        expect(checks, 'marker lands on cursor row', marked.lines[0].text, '> FINALZ');
+        terminal.scrollViewport('top');
+        expect(checks, 'ACTIVE row survives viewport scroll', terminal.readRow(3).text, '> FINALZ');
+        expect(checks, 'VIEWPORT row is history', terminal.readRow(3, { space: 'viewport' }).text, 'old');
+        terminal.write('\x1bc\x1b[?1049hA한é');
+        const alt = terminal.getViewport({ includeRows: 'cursor', cells: true });
+        expect(checks, 'alternate screen', alt.activeScreen, 'alternate');
+        expect(checks, 'cells', alt.lines[0].cells.slice(0, 4).map((cell) => [cell.text, cell.width, cell.wideKind]), [
+            ['A', 1, 'narrow'], ['한', 2, 'wide'], ['', 0, 'spacer-tail'], ['é', 1, 'narrow'],
+        ]);
+        expect(checks, 'legacy formatter still works', terminal.formatPlainText({ trim: true }), 'A한é');
+    } catch (error) {
+        checks.push({ name: 'exercise', ok: false, detail: error.stack || String(error) });
+    } finally {
+        terminal.dispose();
+    }
+    return { file, info, checks };
+}
+
+export function printVerifyReport({ file, checks }, log = console.log) {
+    log(`[ghostty-vt] exercising ${file}`);
+    for (const check of checks) log(`  ${check.ok ? '✓' : '✗'} ${check.name}: ${check.detail}`);
+    const ok = checks.length > 0 && checks.every((check) => check.ok);
+    log(`[ghostty-vt] ${ok ? 'exact prebuilt verified' : 'exact prebuilt FAILED'}`);
+    return ok;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+    const dir = process.argv[2];
+    if (!dir) {
+        console.error('usage: verify-prebuilt.mjs <dir containing ghostty_vt_node.node>');
+        process.exit(2);
+    }
+    if (!printVerifyReport(verifyPrebuilt(resolve(dir)))) process.exit(1);
+}