@gatedpath/preflight 0.1.0 → 0.2.0

package/dist/checks/admin.d.ts

@@ -9,6 +9,8 @@ export declare const SAFE_141_CODE_HASHES: {
     readonly safeL2Singleton: "0xb1f926978a0f44a2c0ec8fe822418ae969bd8c3f18d61e5103100339894f81ff";
     readonly safeProxyFactory: "0x50c3cdc4074750a7a974204a716c999edd37482f907608d960b2b025ee0b3317";
     readonly safeFallbackHandler: "0x7c6007a5d711cea8dfd5d91f5940ec29c7f200fe511eb1fc1397b367af3c42f9";
+    /** The 171-byte runtime code of a SafeProxy made by that factory, the same at every address; derived 2026-09-19 from the fixtures (code hash). */
+    readonly safeProxy: "0xd7d408ebcd99b2b70be43e20253d6d92a8ea8fab29bd3be7f55b10032331fb4c";
 };
 /** keccak256 of runtime code given as a 0x hex string, hashing the bytes rather than the text. */
 export declare function codeHash(codeHex: string): string;
@@ -18,7 +20,10 @@ export interface AdminReading {
     singleton: string | null;
     singletonKind: 'safeSingleton' | 'safeL2Singleton' | null;
     singletonCodeMatches: boolean | null;
+    /** The admin's own runtime code is the SafeProxy 1.4.1 code. Its answers prove nothing; its code does. */
+    proxyCodeMatches: boolean;
     threshold: number | null;
+    ownerCount: number | null;
 }
 export declare function readAdmin(address: string, rpc: string, network: 'mainnet' | 'testnet'): Promise<AdminReading>;
 export declare function checkAdminSafe(admin: string | null, rpc: string, chain: number | null): Promise<CheckResult>;

package/dist/checks/admin.js

@@ -13,8 +13,11 @@ export const SAFE_141_CODE_HASHES = {
     safeL2Singleton: '0xb1f926978a0f44a2c0ec8fe822418ae969bd8c3f18d61e5103100339894f81ff',
     safeProxyFactory: '0x50c3cdc4074750a7a974204a716c999edd37482f907608d960b2b025ee0b3317',
     safeFallbackHandler: '0x7c6007a5d711cea8dfd5d91f5940ec29c7f200fe511eb1fc1397b367af3c42f9',
+    /** The 171-byte runtime code of a SafeProxy made by that factory, the same at every address; derived 2026-09-19 from the fixtures (code hash). */
+    safeProxy: '0xd7d408ebcd99b2b70be43e20253d6d92a8ea8fab29bd3be7f55b10032331fb4c',
 };
 const GET_THRESHOLD = '0xe75235b8'; // getThreshold()
+const GET_OWNERS = '0xa0e67e2b'; // getOwners()
 /** keccak256 of runtime code given as a 0x hex string, hashing the bytes rather than the text. */
 export function codeHash(codeHex) {
     return keccak256Hex(Buffer.from(codeHex.replace(/^0x/, ''), 'hex'));
@@ -22,7 +25,8 @@ export function codeHash(codeHex) {
 export async function readAdmin(address, rpc, network) {
     const caller = toCaller(rpc);
     const code = (await caller('eth_getCode', [address, 'latest']));
-    const reading = { address, isContract: code !== '0x' && code !== '0x0' && code.length > 2, singleton: null, singletonKind: null, singletonCodeMatches: null, threshold: null };
+    const isContract = code !== '0x' && code !== '0x0' && code.length > 2;
+    const reading = { address, isContract, singleton: null, singletonKind: null, singletonCodeMatches: null, proxyCodeMatches: isContract && codeHash(code) === SAFE_141_CODE_HASHES.safeProxy, threshold: null, ownerCount: null };
     if (!reading.isContract)
         return reading;
     const slot0 = (await caller('eth_getStorageAt', [address, '0x0', 'latest']));
@@ -45,11 +49,24 @@ export async function readAdmin(address, rpc, network) {
     catch {
         reading.threshold = null;
     }
+    try {
+        // address[]: an offset word, then the length word
+        const ret = await ethCall(rpc, address, GET_OWNERS);
+        if (ret && ret.length >= 2 + 128)
+            reading.ownerCount = Number(BigInt('0x' + ret.slice(2 + 64, 2 + 128)));
+    }
+    catch {
+        reading.ownerCount = null;
+    }
     return reading;
 }
 export async function checkAdminSafe(admin, rpc, chain) {
-    if (!admin)
-        return { id: 'admin-safe', status: 'skip', reason: 'No admin given; pass --admin <0x…> with the address that will own the deployed contracts.' };
+    if (!admin) {
+        // On mainnet "no admin" is not something to skip past: the report would read ok with nobody named to own the contracts.
+        return chain === 151
+            ? { id: 'admin-safe', status: 'fail', reason: 'No admin given. On mainnet the admin must be named and must be a Safe 1.4.1 with a threshold of at least 2; pass --admin <0x…> or set ADMIN_SAFE.' }
+            : { id: 'admin-safe', status: 'skip', reason: 'No admin given; pass --admin <0x…> with the address that will own the deployed contracts.' };
+    }
     if (!/^0x[0-9a-fA-F]{40}$/.test(admin))
         return { id: 'admin-safe', status: 'fail', reason: `"${admin}" is not a 20-byte hex address.` };
     if (chain !== 151 && chain !== 153)
@@ -69,6 +86,8 @@ export async function checkAdminSafe(admin, rpc, chain) {
             ? { id: 'admin-safe', status: 'fail', reason: `Admin ${admin} is an externally owned account; on mainnet the admin must be a Safe 1.4.1 with a threshold of at least 2.`, data }
             : { id: 'admin-safe', status: 'warn', reason: `Admin ${admin} is an externally owned account; fine on testnet, but mainnet pre-flight will refuse it, so put a Safe in place now.`, data };
     }
+    if (!r.proxyCodeMatches)
+        return { id: 'admin-safe', status: bad, reason: `Admin ${admin} is a contract but not a SafeProxy 1.4.1: its own runtime code does not hash to the proxy the canonical factory creates. What it answers to getThreshold() proves nothing.`, data };
     if (!r.singletonKind)
         return { id: 'admin-safe', status: bad, reason: `Admin ${admin} is a contract but its storage slot 0 (${r.singleton}) is not the canonical Safe 1.4.1 singleton or SafeL2 singleton on this chain.`, data };
     if (r.singletonCodeMatches === false)
@@ -77,5 +96,7 @@ export async function checkAdminSafe(admin, rpc, chain) {
         return { id: 'admin-safe', status: bad, reason: `Admin ${admin} looks like a Safe but getThreshold() did not answer; the proxy may not be set up.`, data };
     if (r.threshold < 2)
         return { id: 'admin-safe', status: bad, reason: `Admin ${admin} is a Safe 1.4.1 with threshold ${r.threshold}; one signer is one stolen key away from your contracts, so use 2 or more.`, data };
-    return { id: 'admin-safe', status: 'pass', reason: `Admin ${admin} is a Safe 1.4.1 (${r.singletonKind === 'safeL2Singleton' ? 'SafeL2' : 'Safe'} singleton, code hash verified) with threshold ${r.threshold}.`, data };
+    if (r.ownerCount === null || r.ownerCount < r.threshold)
+        return { id: 'admin-safe', status: bad, reason: `Admin ${admin} is a Safe 1.4.1 with threshold ${r.threshold} but ${r.ownerCount ?? 'an unreadable number of'} owners; it could never sign.`, data };
+    return { id: 'admin-safe', status: 'pass', reason: `Admin ${admin} is a Safe 1.4.1 (${r.singletonKind === 'safeL2Singleton' ? 'SafeL2' : 'Safe'} singleton; proxy and singleton code hashes verified) with threshold ${r.threshold} of ${r.ownerCount} owners.`, data };
 }

package/dist/checks/deployer.js

@@ -38,7 +38,9 @@ export async function checkDeployerVerified(address, how, error, rpc, chain) {
         if (isWellKnownDevAccount(address)) {
             return {
                 id: 'deployer-verified',
-                status: 'warn',
+                // Anyone can sign as this account. On mainnet that is a refusal, and so is failing isAllowed
+                // anywhere; a warning is only right on testnet when the account does pass.
+                status: chain === 151 || !allowed ? 'fail' : 'warn',
                 reason: `${address} (${how}) is one of the ten anvil/Hardhat default accounts whose private keys are public; it ${allowed ? 'passes' : 'fails'} isAllowed on chain ${chain}, but a deploy from it runs under an identity you do not control (RESEARCH.md question 30). Use a keystore of your own.`,
                 data: { address, allowed, how, wellKnownDevAccount: true },
             };

package/dist/checks/git-secrets.d.ts

@@ -5,6 +5,8 @@ export interface SecretFinding {
     kind: string;
     why: string;
 }
+/** True when the history scan leaves this path alone. Exported for the tests. */
+export declare function ignoredPath(file: string): boolean;
 export declare function scanGitHistory(project: string): Promise<{
     findings: SecretFinding[];
     commits: number;

package/dist/checks/git-secrets.js

@@ -5,7 +5,15 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { scanLine } from '../secrets.js';
-const IGNORED_PATHS = /(^|\/)(node_modules|lib|out|cache|artifacts|typechain(-types)?)\/|(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|\.gas-snapshot)$|\.(min\.js|map|svg|png|jpg|pdf)$/;
+// Vendor and build roots only, where a project keeps them: the repository root, `contracts/` or
+// `hardhat/`. `node_modules` is vendor at any depth. A folder that merely shares a name, such as
+// `src/lib/wallet.ts`, is the builder's own code and is scanned (audit of 2026-09-19). The Slither
+// sidecar is a bare hash by design.
+const IGNORED_PATHS = /(^|\/)node_modules\/|^((contracts|hardhat)\/)?(lib|out|cache|artifacts|typechain(-types)?)\/|(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|\.gas-snapshot)$|\.(min\.js|map|svg|png|jpg|pdf|sha256)$/;
+/** True when the history scan leaves this path alone. Exported for the tests. */
+export function ignoredPath(file) {
+    return IGNORED_PATHS.test(file);
+}
 const MAX_FINDINGS = 25;
 export async function scanGitHistory(project) {
     const isRepo = await run('git', ['rev-parse', '--is-inside-work-tree'], project).then((r) => r.code === 0 && r.stdout.trim() === 'true');

package/dist/checks/slither.js

@@ -10,7 +10,7 @@
 // 2026-09-12 running the prompt cards), which is why the hash sidecar exists.
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, realpathSync } from 'node:fs';
 import { dirname, join, relative, sep } from 'node:path';
 import { run } from '../proc.js';
 export const DEFAULT_REPORT_PATHS = ['reports/slither.json', 'reports/slither.md', 'slither.json', 'slither-report.json', 'slither.md'];
@@ -95,10 +95,21 @@ async function fileTimes(project, files) {
             out.set(f, mtime(f));
         return out;
     }
-    const status = await run('git', ['status', '--porcelain', '--untracked-files=all', '--', ...files], { cwd: project, timeoutMs: 30_000 });
-    const dirty = new Set(status.stdout.split('\n').filter(Boolean).map((l) => join(repoRoot(project), l.slice(3).trim())));
+    // `-z`: NUL-separated and unquoted, so a path with a space is not wrapped in quotes. Both sides are
+    // resolved to real paths: git prints the repository's real root, while `project` may have been
+    // reached through a symlink (`/tmp` on macOS). Compared as plain strings, an edited source was
+    // never seen and a stale report passed (audit of 2026-09-19).
+    const status = await run('git', ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...files], { cwd: project, timeoutMs: 30_000 });
+    const real = (f) => { try {
+        return realpathSync(f);
+    }
+    catch {
+        return f;
+    } };
+    const root = repoRoot(project);
+    const dirty = new Set(status.stdout.split('\0').filter(Boolean).map((l) => real(join(root, l.slice(3)))));
     for (const f of files) {
-        if (dirty.has(f)) {
+        if (dirty.has(real(f))) {
             out.set(f, mtime(f));
             continue;
         }

package/dist/index.d.ts

@@ -3,9 +3,9 @@ export type { RunOptions } from './run.js';
 export type { CheckId, CheckResult, CheckStatus, PreflightOptions, PreflightReport } from './types.js';
 export { readProjectConfig, parseToml, readFoundryConfig, readHardhatConfig, HARDHAT_CONFIG_NAMES } from './config.js';
 export type { ProjectConfig } from './config.js';
-export { scanLine, scanText, scanValue, mnemonicRun } from './secrets.js';
+export { scanLine, scanText, scanValue, mnemonicRun, provenHashes } from './secrets.js';
 export type { SecretKind, SecretMatch } from './secrets.js';
-export { scanGitHistory, checkGitSecrets } from './checks/git-secrets.js';
+export { scanGitHistory, checkGitSecrets, ignoredPath } from './checks/git-secrets.js';
 export { readAdmin, checkAdminSafe, codeHash, SAFE_141_CODE_HASHES } from './checks/admin.js';
 export { checkCompilerPins, SOLC_PIN, EVM_PIN } from './checks/compiler.js';
 export { checkBalance, MARGIN_PERCENT } from './checks/balance.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 export { runPreflight, renderText, CHECK_IDS, DEFAULT_GAS, VERSION } from './run.js';
 export { readProjectConfig, parseToml, readFoundryConfig, readHardhatConfig, HARDHAT_CONFIG_NAMES } from './config.js';
-export { scanLine, scanText, scanValue, mnemonicRun } from './secrets.js';
-export { scanGitHistory, checkGitSecrets } from './checks/git-secrets.js';
+export { scanLine, scanText, scanValue, mnemonicRun, provenHashes } from './secrets.js';
+export { scanGitHistory, checkGitSecrets, ignoredPath } from './checks/git-secrets.js';
 export { readAdmin, checkAdminSafe, codeHash, SAFE_141_CODE_HASHES } from './checks/admin.js';
 export { checkCompilerPins, SOLC_PIN, EVM_PIN } from './checks/compiler.js';
 export { checkBalance, MARGIN_PERCENT } from './checks/balance.js';

package/dist/run.js

@@ -70,9 +70,17 @@ export async function runPreflight(opts = {}) {
         deployer: deployer.address,
         admin,
         checks,
-        ok: checks.every((c) => c.status !== 'fail'),
+        ok: checks.every((c) => c.status !== 'fail') && !skipsForbidOk(skip, reported ?? expected),
+        skippedOnRequest: skip.size,
     };
 }
+/** A requested skip that "ok" cannot survive: anything on mainnet, the chain check anywhere, or everything. */
+function skipsForbidOk(skip, chain) {
+    if (skip.size === 0)
+        return false;
+    return chain === 151 || skip.has('chain-id') || skip.size >= ALL_CHECKS;
+}
+const ALL_CHECKS = 7;
 function defaultRpc(chain) {
     const c = chainById(chain === 151 ? 151 : 153);
     if (!c)
@@ -101,6 +109,22 @@ export function renderText(report) {
     lines.push('');
     const fails = report.checks.filter((c) => c.status === 'fail').length;
     const warns = report.checks.filter((c) => c.status === 'warn').length;
-    lines.push(report.ok ? `ok: no check failed${warns ? ` (${warns} warning${warns === 1 ? '' : 's'})` : ''}.` : `not ok: ${fails} check${fails === 1 ? '' : 's'} failed. Do not deploy.`);
+    const skipped = report.skippedOnRequest;
+    if (report.ok) {
+        const notes = [warns ? `${warns} warning${warns === 1 ? '' : 's'}` : '', skipped ? `${skipped} skipped on request, so not checked` : ''].filter(Boolean);
+        lines.push(`ok: no check failed${notes.length ? ` (${notes.join('; ')})` : ''}.`);
+    }
+    else if (fails > 0) {
+        lines.push(`not ok: ${fails} check${fails === 1 ? '' : 's'} failed. Do not deploy.`);
+    }
+    else if (skipped >= ALL_CHECKS) {
+        lines.push('not ok: every check was skipped, so nothing was checked.');
+    }
+    else if (report.chain.reported === 151 || report.chain.expected === 151) {
+        lines.push(`not ok: ${skipped} check${skipped === 1 ? ' was' : 's were'} skipped on request, and chain 151 accepts no skipped check.`);
+    }
+    else {
+        lines.push('not ok: the chain check was skipped, so nothing says which network this is.');
+    }
     return lines.join('\n') + '\n';
 }

package/dist/secrets.d.ts

@@ -4,6 +4,11 @@ export interface SecretMatch {
     /** Why this counts. One sentence, no secret material. */
     readonly why: string;
 }
+/**
+ * Hashes a line proves about itself: `keccak256("X")` beside a value that really is keccak256 of X,
+ * where X is shaped like a role name. A key cannot be dressed up that way without its preimage.
+ */
+export declare function provenHashes(line: string): Set<string>;
 /** Every secret-shaped thing on one line of text. */
 export declare function scanLine(line: string): SecretMatch[];
 /** True when the line holds 12+ consecutive BIP-39 words separated by single spaces. */

package/dist/secrets.js

@@ -1,14 +1,32 @@
 // Spots secret-shaped text. Used by the git-history check here and by the MCP server's
 // argument guard. It reports the kind of match and where, never the matched text.
+import { keccak256Hex } from '@gatedpath/chains';
 import { BIP39_ENGLISH } from './bip39-words.js';
 const HEX64 = /(?<![0-9a-fA-F])(0x)?[0-9a-fA-F]{64}(?![0-9a-fA-F])/g;
-/** A 0x-prefixed 64-hex string is usually a hash. It reads as a key when the line says so. */
-const KEY_WORDS = /\b(private[_ -]?key|privkey|secret|signer[_ -]?key|deployer[_ -]?key|wallet[_ -]?key|mnemonic|seed)\b/i;
+// Word edges that treat `_` as an edge. `\b` does not: `_` is a word character, so `\bPRIVATE_KEY\b`
+// never fired inside REDBELLY_PRIVATE_KEY, and that shape passed the scan (audit of 2026-09-19).
+const L = '(?<![A-Za-z0-9])';
+const R = '(?![A-Za-z0-9])';
+/** Words that make a 0x 64-hex value a key whatever else the line says. */
+const KEY_WORDS = new RegExp(`${L}(private[_ -]?key|priv[_ -]?key|privkey|pk|secret|signer[_ -]?key|deployer[_ -]?key|wallet[_ -]?key|mnemonic|seed|startBroadcast|privateKeyToAccount)${R}`, 'i');
+/** Weaker signs: a key is likely, unless the line is plainly about a hash. A Hardhat `accounts` array is the commonest leak there is. */
+const KEYISH_WORDS = new RegExp(`${L}(accounts?|wallet|signer|key)${R}|new Wallet\\(`, 'i');
 /** Lines that are plainly about hashes stay quiet even without the 0x prefix. */
-const HASH_WORDS = /"id"\s*:|\b(sha-?256|sha-?512|sha-?3|keccak|blake2?b?|integrity|checksum|digest|codehash|code hash|tx ?hash|transactionHash|blockHash|merkle|root)\b/i;
-const KEY_ASSIGNMENT = /\b(PRIVATE_KEY|PRIV_KEY|DEPLOYER_KEY|DEPLOYER_PRIVATE_KEY|WALLET_KEY|SIGNER_KEY|MNEMONIC|SEED_PHRASE|SEED)\b\s*[=:]\s*["'`]?([^\s"'`#]+(?:\s+[a-z]+)*)/;
+const HASH_WORDS = /"id"\s*:|\b(sha-?256|sha-?512|sha-?3|keccak|blake2?b?|integrity|checksum|digest|codehash|code hash|tx ?hash|transactionHash|blockHash|merkle|root|slot|topic|salt)\b|hash/i;
+const KEY_ASSIGNMENT = new RegExp(`${L}((?:[A-Z0-9]+_)*(?:PRIVATE_KEY|PRIV_KEY|DEPLOYER_KEY|DEPLOYER_PRIVATE_KEY|WALLET_KEY|SIGNER_KEY|MNEMONIC|SEED_PHRASE|SEED|PK))${R}\\s*[=:]\\s*["'\`]?([^\\s"'\`#]+(?:\\s+[a-z]+)*)`);
 const PLACEHOLDER = /^(<|\$|\{\{|your|xxx+|\.\.\.|changeme|replace|example|0x0+$|todo|none|null|undefined|""|'')/i;
 const KEYSTORE = /"(ciphertext|kdfparams|mac)"\s*:/;
+/**
+ * Hashes a line proves about itself: `keccak256("X")` beside a value that really is keccak256 of X,
+ * where X is shaped like a role name. A key cannot be dressed up that way without its preimage.
+ */
+export function provenHashes(line) {
+    const proven = new Set();
+    for (const m of line.matchAll(/keccak256\(\\?"([A-Z][A-Z0-9_]*)\\?"\)/g)) {
+        proven.add(keccak256Hex(new TextEncoder().encode(m[1])).toLowerCase());
+    }
+    return proven;
+}
 /** Every secret-shaped thing on one line of text. */
 export function scanLine(line) {
     const out = [];
@@ -17,8 +35,17 @@ export function scanLine(line) {
     for (const m of line.matchAll(HEX64)) {
         const prefixed = m[1] === '0x';
         if (prefixed) {
-            if (KEY_WORDS.test(line))
+            const proven = provenHashes(line);
+            if (proven.has(m[0].toLowerCase()))
+                continue;
+            if (proven.size > 0) {
+                // The line names a preimage, and this value is not its hash: whatever it is, it is not what it says.
+                out.push({ kind: 'hex64-keyword', why: 'a 0x-prefixed 64-hex value beside a keccak256("...") that does not hash to it' });
+                continue;
+            }
+            if (KEY_WORDS.test(line) || (KEYISH_WORDS.test(line) && !HASH_WORDS.test(line))) {
                 out.push({ kind: 'hex64-keyword', why: 'a 0x-prefixed 64-hex value on a line that talks about a key' });
+            }
         }
         else if (!HASH_WORDS.test(line)) {
             out.push({ kind: 'hex64', why: 'a bare 64-hex value, the shape of a private key in a .env or keystore export' });

package/dist/ship-cli.js

@@ -1,7 +1,7 @@
 // `redbelly ship`: the mainnet gate that writes its own report. Exit 0 when every check passed and
 // deployments/ship-<chain>-<date>.md was written, 1 when a check failed (nothing written), 2 on bad
 // arguments. --json for agents. Never takes a key: --account names a keystore that cast reads.
-import { SHIP_VERSION, renderShipText, runShip, shipReportJson } from './ship.js';
+import { SHIP_VERSION, renderShipText, runShip, shipReportJson, ShipUsageError } from './ship.js';
 export const SHIP_HELP = `redbelly ship --chain <151|153> --account <keystore-name> [options]
 
 Runs pre-flight (seven checks) with the keystore's address, checks the Slither sidecar, runs
@@ -123,6 +123,6 @@ export async function shipMain(argv = process.argv.slice(2)) {
     }
     catch (e) {
         process.stderr.write(`redbelly ship: ${e.message}\n`);
-        return 1;
+        return e instanceof ShipUsageError ? 2 : 1;
     }
 }

package/dist/ship.d.ts

@@ -103,6 +103,15 @@ export declare function routescanBase(chain: 151 | 153): {
 /** The deployment records the deploy script wrote for this chain, with the verify command each needs. */
 export declare function readShipContracts(dir: string, chain: 151 | 153, pins: ShipReport['pins']): ShipContract[];
 export declare function runShip(opts: ShipOptions): Promise<ShipReport>;
+/**
+ * The deploy scripts find today's report by its name, `ship-<chain>-<date>.md`. `--out` may put the
+ * report anywhere, except under a name that says it is for a different chain: a passing testnet
+ * report must never sit where the mainnet gate looks (audit of 2026-09-19).
+ */
+export declare function refuseAnotherChainsName(out: string, chain: number): void;
+/** A mistake in how ship was called, as opposed to a check that failed. The CLI exits 2 on it. */
+export declare class ShipUsageError extends Error {
+}
 export declare function renderShipMarkdown(r: ShipReport): string;
 export declare function renderShipText(r: ShipReport): string;
 export declare function shipReportJson(report: ShipReport): string;

package/dist/ship.js

@@ -98,6 +98,8 @@ export async function runShip(opts) {
     if (!existsSync(join(dir, 'foundry.toml')))
         throw new Error(`no foundry.toml in ${project} or ${join(project, 'contracts')}; ship drives forge and reads the Foundry project`);
     const chain = opts.chain;
+    if (opts.out)
+        refuseAnotherChainsName(resolve(dir, opts.out), chain); // before any work: this is a usage mistake
     const network = chain === 151 ? 'mainnet' : 'testnet';
     const dotenv = readDotEnv(dir, env);
     const rootEnv = dir === project ? dotenv : { ...readDotEnv(project, env), ...dotenv };
@@ -267,6 +269,20 @@ export async function runShip(opts) {
     writeFileSync(out, renderShipMarkdown(report));
     return { ...report, written: out };
 }
+/**
+ * The deploy scripts find today's report by its name, `ship-<chain>-<date>.md`. `--out` may put the
+ * report anywhere, except under a name that says it is for a different chain: a passing testnet
+ * report must never sit where the mainnet gate looks (audit of 2026-09-19).
+ */
+export function refuseAnotherChainsName(out, chain) {
+    const named = /^ship-(\d+)-/.exec(basename(out));
+    if (named && Number(named[1]) !== chain) {
+        throw new ShipUsageError(`--out names a ship report for chain ${named[1]}, and this run is for chain ${chain}. Choose another name, or leave --out off.`);
+    }
+}
+/** A mistake in how ship was called, as opposed to a check that failed. The CLI exits 2 on it. */
+export class ShipUsageError extends Error {
+}
 // ---- the document ----
 const fmt = (n) => n.toLocaleString('en-US');
 const short = (s) => (s && s.includes('.') ? s.replace(/(\.\d{4})\d+$/, '$1') : s ?? '');

package/dist/types.d.ts

@@ -53,6 +53,13 @@ export interface PreflightReport {
     readonly deployer: string | null;
     readonly admin: string | null;
     readonly checks: readonly CheckResult[];
-    /** True when no check failed. Warnings and skips do not clear a fail and do not cause one. */
+    /**
+     * True when no check failed and the run checked something. A check skipped because it does not
+     * apply is neutral. A check skipped ON REQUEST is neutral on testnet, and makes this false on
+     * chain 151 or when the chain check itself, or every check, was skipped: "ok" must never mean
+     * "nothing was looked at".
+     */
     readonly ok: boolean;
+    /** How many checks `--skip` removed. */
+    readonly skippedOnRequest: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatedpath/preflight",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pre-flight checks before deploying to Redbelly Network (151 mainnet, 153 testnet): chain ID, deployer verification, Safe admin, compiler pins, secrets in git history, RBNT balance, Slither report.",
   "license": "MIT",
   "repository": {
@@ -25,9 +25,9 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "redbelly-preflight": "./dist/cli.js",
-    "redbelly-doctor": "./dist/doctor-cli.js",
-    "redbelly": "./dist/redbelly.js"
+    "redbelly-preflight": "dist/cli.js",
+    "redbelly-doctor": "dist/doctor-cli.js",
+    "redbelly": "dist/redbelly.js"
   },
   "files": [
     "dist",
@@ -40,11 +40,12 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@gatedpath/agent-rules": "0.1.0",
-    "@gatedpath/chains": "0.1.0"
+    "@gatedpath/agent-rules": "0.2.0",
+    "@gatedpath/chains": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.2",
     "typescript": "^5.9.3"
-  }
+  },
+  "preferUnplugged": true
 }