border-customs 0.8.3 → 0.8.5

package/README.md

@@ -40,6 +40,10 @@ source checkout. Every check and push record carries `engineBuild` — the ident
 `border --version` prints. A `.dirty` suffix means the verdict came from uncommitted code, and
 records from one repo carrying different `engineBuild` values mean the audit trail is mixed:
 both are findings an auditor should chase, which is exactly why the identity is on the record face.
+Freshness telemetry (the `global-resolution` WARN rung, drift-watch rc 3, and heartbeat lines) is
+read-only information. Pinned consumption governs the install and execution surfaces: running an
+older, deliberately chosen version is a legitimate steady state, not a defect. The decision to
+update always stays with the human operator. (Owner-approved clarification, 2026-11-06.)
 
 ## The problem it solves
 
@@ -59,7 +63,11 @@ pushed" includes the six things people forget:
 
 - **Untracked and dirty files are inputs too.** History scanning alone misses the `.env`
   that was never committed but will ride along in a `git add -A`. border fingerprints the
-  full `git status --porcelain` digest and scans the working tree directly.
+  full `git status --porcelain` digest and scans the working tree directly. One carve-out is
+  provably unpushable and demoted to INFO (never silently dropped): paths that are
+  `.gitignore`'d **and** untracked — `git add` honours `.gitignore`, so they can only reach a
+  commit through a deliberate `git add -f`, which moves them into the tracked surface where
+  the full gate applies. Blocking on them would train operators to mute the gate.
 - **Deleted-but-pushed blobs.** A secret removed in a later commit still ships in the
   history of the ref being pushed. The history leg scans everything the push would
   transmit, not just HEAD.
@@ -129,9 +137,13 @@ it, and the two registry-facing legs (pre-flight and publish) both have to agree
    (`.omo/**`, `**/transcripts/**`, `*.session.jsonl`, `opencode.json(c)`, `.opencode/**`,
    env files except `.env.example`/`.env.sample`, junk like `probe*`/`*.rej`/
    `node_modules/**`, plus your `rules.pathPatterns` through the same compiler). Identity
-   allow-listing over commit authors, merge committers, and annotated-tag taggers, checked
-   against the history of every ref *and* against the object set a remote does not already
-   have (the transmit set). Oversized-file, checked-in-binary, and notebook-output rules
+   allow-listing over commit authors, merge committers, and annotated-tag taggers, split by
+   *exposure class* against each configured remote's **live** `git ls-remote` (never a stale
+   local tracking ref): objects leaving the machine for the first time are CRITICAL
+   `identity-not-allowlisted`; offenders the remote already carries everywhere are recorded as
+   INFO `identity-already-public` without remediation — border never advises rewriting
+   published history. Offenders plus an unreachable remote exit 2 (the exposure class is
+   never guessed); no configured remote means first-push semantics (all fresh). Oversized-file, checked-in-binary, and notebook-output rules
    round it out.
 7. **Landing-grade tip lens.** The exact machinery `border push` uses to verify a landing
    (`scanTipTree`: the tip tree materialized from git objects into a throwaway directory,
@@ -608,38 +620,10 @@ dropped file to stderr with the sha256 of its original bytes
 (`border scan: crates envelope normalized: <file> sha256=<hex>`); the rebuild regenerates
 them from the normalized manifest, so no scanned byte is silently lost.
 
-### Engines in consumer installs
-
-`dist/index.js` is one self-contained esbuild bundle and every runtime asset (vendored
-gitleaks rules, prompt template, the secretlint fingerprint snapshot) ships inside `dist/`,
-so after `npm i -D border-customs` (or `-g`) the engine surface is:
-
-- **publint** — installed automatically: it is an exact-pinned runtime dependency of the
-  package, invoked via bin resolution (package-local `node_modules/.bin`, the hoisted
-  project-level `node_modules/.bin`, then `PATH`, then `~/.local/bin`). The
-  `publint-fail` leg of the npm artifact stage works out of the box in a consumer install.
-- **secretlint** — no consumer action, ever: the default lint runs **in-process** with the
-  `@secretlint/*` rule modules already declared as border's own runtime dependencies
-  (`src/engines/secretlint.ts` header). The `mode: "cli"` fallback that spawns a
-  `secretlint` binary is border-internal (test transport); it is not reachable from
-  `border.yaml` or any flag, so installing `secretlint` into your project changes nothing
-  for border. If the engine probe cannot read the bundled lock snapshot
-  (`dist/assets/package-lock.json`), the run fails closed as `DEGRADED-ENGINE` exit 2 —
-  never a silent pass.
-- **gitleaks** — stays external, same posture as `git`: border vendors the 8.30.1 rule
-  config but the binary is yours (on `PATH` or `~/.local/bin/gitleaks`; see the
-  requirements paragraph at the top and `src/engines/ADAPTER-CONTRACT.md`). Missing
-  gitleaks means `border check` records a CRITICAL `DEGRADED-ENGINE` finding and exits 2,
-  and `border scan` exits 2 with `engine binary 'gitleaks' not found; border fails
-  closed`. Neither command degrades to a skip.
-- **trufflehog** — optional third engine, external binary, same posture as gitleaks once
-  enabled: `engines.trufflehog: true` puts it in the required set, and an absent binary
-  degrades the run to exit 2 exactly like a missing gitleaks.
-
-There is no "engine absent ⇒ leg silently skipped" state anywhere: missing required
-engines are exit 2 (`2` = the gate could not answer, see
-[Exit codes](#exit-codes-the-contract)), and the ledger refuses to write a PASS for a
-degraded run.
+## Engines
+
+Engine posture per scanner — vendored vs external, version matrices,
+consumer-install behavior: [docs/engines.md](docs/engines.md).
 
 ## Configuration
 
@@ -839,7 +823,7 @@ plugin entry ships as `exports["./server"]`):
 ```jsonc
 {
   // pin the exact version — an @latest channel hits the registry on every cold start
-  "plugin": ["border-customs@0.8.3"]
+  "plugin": ["border-customs@0.8.5"]
 }
 ```
 
@@ -877,7 +861,12 @@ argv-only (no shell; 300 s cap, 64 KiB per stream) restricted to the closed comm
 `check`, `push`, `status`, `llm-request`, `llm-ingest`, `scan`, `roundtrip`, `exfil`, `--help`, and
 renders the exit-code contract unchanged: 0 pass, 1 gate-blocked or partial push, 2 the gate
 could not answer — which since 0.5.1 also covers "no border CLI found or verified": the tool
-answers exit 2 cannot-answer and spawns nothing else. The tool REFUSES `--yes` — a real push
+answers exit 2 cannot-answer and spawns nothing else. Every result carries a
+`face: <resolved candidate> version=<--version stamp>` line: the identity handshake proves *which
+binary*, the stamp line makes *which version* observable on every call (a PATH-fallback to an older
+published CLI is loud, never silent). `BORDER_REQUIRE_PKG_VERSION=1` escalates that to a gate: the
+resolved CLI must report the plugin package's own version or the call is refused as cannot-answer
+with nothing spawned. The tool REFUSES `--yes` — a real push
 is the human gate, terminal-only, and a bare `border push` from the session is DRY-RUN by the
 CLI's own contract anyway. `/border` self-registers via the plugin `config` hook with `??=`, so
 a user file command of the same name — including a Route-A `commands/border.md` — stays
@@ -892,16 +881,24 @@ fails); plugin load failures are silent, so judge by the HTTP responses, never b
 code.
 
 `border opencode inspect [--json]` audits this machine's **V1 load surface** as one gate-owned
-command: six read-only aspects — cache self-consistency (package.json vs plugin marker line),
+command: seven read-only aspects — cache self-consistency (package.json vs plugin marker line),
 spec freshness (exact pin offline; dist-tag against the registry), the 0.5.1 identity handshake
 replayed against the CLI resolver's candidate order, Route A byte parity, Route A∧B dual-registration
-collision, and the scope declaration — aggregated fail-closed: any FAIL exits 1, else any CANNOT
-exits 2, all PASS exits 0. The certificate boundary is printed, not implied: `--json` carries
+collision, the scope declaration, and global-resolution (which CLI build answers on which face —
+`BORDER_BIN`, packaged dist, PATH — and whether the active face lags the registry's latest) —
+aggregated fail-closed: any FAIL exits 1, else any CANNOT exits 2, else 0. The seventh aspect's lag
+rung is **WARN — informational**: lag under pinned consumption is a legitimate steady state, so WARN
+never moves the aggregate or any purge trigger; registry-unreachable for this aspect stays named.
+`BORDER_INSPECT_OFFLINE=1` skips the freshness leg explicitly on air-gapped machines — the aspect
+then reports WARN "skipped", never fresh (an unevaluated face is never reported as fresh).
+The certificate boundary is printed, not implied: `--json` carries
 `scope:"v1"`, and V2 load surfaces (project-local `.opencode/plugins/`, npm-prefix layouts, lazy
 activation) are a DECLARED BLIND SPOT pending V2 stabilization — a PASS is never evidence that
 "the whole machine is clean". The tool never writes: `--purge` lives in the drift-watch cron shell,
-which is now a thin consumer of `inspect --json` with the rc contract unchanged
-(FRESH 0 / DRIFT 1 / NOT-CACHED 0 / CANNOT 2).
+which is now a thin consumer of `inspect --json` with rc contract FRESH 0 / DRIFT 1 / NOT-CACHED 0 /
+CANNOT 2 / **GLOBAL-WARN or GLOBAL-UNREACHABLE 3** (warn-only by construction: the cron purge guard
+acts on rc 1 only, and rc 3 can never reach it), plus an optional `--heartbeat <path>` that appends
+one `ISO / verdict / rc / bin` line per run.
 
 ## What this is not
 
@@ -969,271 +966,9 @@ and every pull request, plus version single-source, typecheck, build, and audit
 
 ## Changelog
 
-### 0.8.3 (2026-11-02)
-- Fix: `exfil-cred-location` is now syntax-aware in JS/TS sources (handoff b61b42a) —
-  `.env` tokens count only inside string-literal spans (TypeScript compiler API, shipped
-  as a runtime dependency, bundle stays external-pinned); member accesses (`opts.env`),
-  short receivers and comment text are no longer reported. Markdown/text keep the
-  bare-mention behavior; every other rule is untouched. All tree faces (check, history,
-  tip lens) share the guard; parse failure ⇒ old behavior + one stderr note, exit codes
-  unchanged. Rules fingerprint rotated (cached PASSes re-verify once).
-
-### 0.8.2 (2026-11-01)
-- Production dependency graph now measures ZERO advisories (`npm audit --omit=dev`): the
-  pattern rule is vendored (`src/engines/borderPatternRule.ts`, MIT attribution; drops the
-  unpatchable braces/micromatch + fast-uri chain) and `tool` — an identity function — is
-  vendored in `plugin/border.ts`, moving `@opencode-ai/plugin` (and its effect-beta → toml
-  chain) to devDependencies; live-host probe tests keep the activation proof. The CI audit
-  gate tightens from critical to HIGH so this cannot rot.
-- `border sandbox init|pin|status|unpin` — the opt-in pin helper from the Q1 ruling
-  (machine store only, 0600 atomic writes, §3 self-verification with rollback of its own
-  writes; deliberately absent from the plugin's agent-reachable command set).
-- Security tier for execution-deciding keys (`src/tier.ts`, sibyl §3⁗/§3⁖/§3‡):
-  `sandboxImage`/`allowBuilds` honor only from fd-chain-qualified machine-store or out-of-repo
-  `--config` sources; repo declarations, lax-mode files, and hijacked `XDG_CONFIG_HOME` are
-  named refusals (`sandbox-config-shadowed`/`sandbox-config-unqualified`); the
-  `BORDER_ALLOW_BUILDS` environment channel is REMOVED (never released, so no migration);
-  passwd-derived canonical store root — `$HOME` spoofing cannot move it.
-- Sandboxed artifact builds: optional `targets.<ch>.sandboxImage` (digest-pinned, tags fail
-  closed at load) runs consented npm/pypi/crates/rubygems builds — and freshness re-packs —
-  inside `docker run` with `--network none` proved by an in-container DNS+TCP probe, a
-  read-only repo mount, tmpfs build, `--cap-drop ALL`, scrubbed env, and the ledger record
-  bound to the exact image digest (a rotated image invalidates cached PASS). Missing docker
-  with an image configured is a named exit 2, never a host fallback. New `test/sandbox.test.ts`
-  pins the docker argv contract token by token.
-- Hardened the npm pack-phase guard (sibyl must_fix): ALL package.json manifests in the tree
-  are scanned, not just the root (a workspaces child's `prepare` is now refused on npm < 11),
-  and unreadable manifests or a walk-cap hit count as a hook — unknown is never assumed safe.
-- Machine-side config (HR decoupling handoff 2026-10-23): resolution chain is now
-  `--config > $BORDER_CONFIG (fail-closed) > machine store (XDG/border/machines, keyed by
-  canonical remote URL) > ./border.yaml > git-remote inference`, so gate config and waiver
-  lists live on the checking machine and never need to be committed into a product repo.
-  Allow entries gained `values` (fixture-set waivers that never cover a new value), `until`
-  (UTC sunset, expired entries echoed never silently honored), `\!` archive-member escaping,
-  and `rules.aliases` (rule renames no longer strand waivers). Border state was already
-  porcelain-invisible (`.border/.gitignore` self-ignore; verified 2026-10-23).
-- Provenance: every check and push record carries `engineBuild`
-  (`<version>+<commit>[.dirty]`, the string `border --version` prints), so a verdict names
-  the exact border build that produced it. Motivated by a machine where every gate ran off
-  an unpinned worktree bundle and no record said so; worktree use is now visible on the
-  record face (see "Pinned consumption"). Bundles are stamped by `tools/build.mjs`.
-- Security (breaking): artifact build stages now require operator consent. A hostile clone can
-  ship its own border.yaml declaring pypi/rubygems targets, and `border check` built them —
-  PEP 517 backends and gemspecs ARE code (`python3 -m build --no-isolation` and `gem build`
-  markers reproduced 2026-10-23). Default runs are now scan-only (zero build spawns, pinned by
-  `test/build.execMarkers.test.ts`); consent comes only from outside the audited tree:
-  `--allow-builds` or `BORDER_ALLOW_BUILDS=1`. A scan-only PASS records no artifact digests and
-  therefore can never back a registry publish; `border scan` of third-party artifacts requires
-  the same consent (named exit 2 without it).
-- Security: refuse npm < 11 packages that declare `prepack`/`prepare`/`postpack` before
-  spawning `npm pack`. npm 10 executes `prepare` even with `--ignore-scripts` (reproduced on
-  10.9.7; npm 11.19.1 is clean), so the old defense could execute code from the audited repo.
-  The probe also runs before freshness re-packs. New regression tests pin the refusal and the
-  never-fires hook marker.
-- Fix: the Windows drive-letter path pattern no longer fires on JS escapes in prose
-  (`raw-repoPath:\n`); the UNC pattern no longer spans newlines.
-- Docs: the `--json` findings schema is stated explicitly (`path`, no `file` alias);
-  npm-target prerequisites now name the npm 11 boundary.
-
-### 0.8.1 (2026-10-06)
-- Maintenance release: certificate-chain rebuild off the scrubbed lineage (INCIDENT-20261006
-  identity-exposure cleanup). No functional change vs 0.8.0; 0.8.0's tarball is byte-intact but
-  its OIDC provenance pin moved with the history rewrite, so a fresh tag + publish restores a
-  verifiable chain. Rotation: package.json + lock roots + plugin marker + scan UA + README pins +
-  this entry.
-
-### 0.8.0 (2026-09-30)
-- Add: **`border opencode inspect [--json]`** — the load-surface self-audit becomes a gate-owned
-  surface: six read-only aspects (cache self-consistency, spec freshness vs pin/registry, identity
-  handshake replay, Route A byte parity, Route A∧B dual-route collision, scope declaration),
-  fail-closed aggregation FAIL 1 > CANNOT 2 > PASS 0. `--json` pins `scope:"v1"` — V2 load surfaces
-  are a declared blind spot, not silently covered. Zero writes; `--purge` stays in the cron shell.
-- Change: **`exfil` joins the plugin's closed command list** (owner ruling R1 under the four-question
-  eligibility gate — no mutation, no credentials, no foreign-byte execution, no local egress;
-  packet: `.omo/evidence/F-EXFIL-ALLOWLIST-RULING-2026-09-30.md`). `border opencode …` verbs stay
-  terminal-only: they mutate `$XDG_CONFIG_HOME` and fail the gate's first question.
-- Change: `tools/plugin-drift-watch.mjs` retires to a thin shell over `border opencode inspect --json`
-  (single source of verdicts); the cron rc contract is byte-stable — FRESH 0, DRIFT 1, NOT-CACHED 0
-  (special-cased per ruling B2), CANNOT 2 — and the crontab line is unchanged.
-
-### 0.7.1 (2026-09-30)
-- Fix: **release-gate test ruler race** (`test/push.integration.test.ts` I4) — the
-  "dry-run made ZERO verdaccio requests" invariant counted lines in verdaccio's stdout
-  log, an eventually-consistent view: on a saturated CI runner the gate-leg probe lines
-  of an earlier phase land after the snapshot, inflating the dry-run delta (v0.7.0 CI
-  run 36671401844 failed `6 !== 2` while the identical bytes pass locally). The suite
-  now takes every snapshot through a FIFO drain barrier (sentinel request whose log line
-  must be visible before counting; sentinel traffic is excluded from the count). The
-  zero-network dry-run contract itself is unchanged — verified request-free on both sides
-  of the barrier; only the measuring instrument was repaired.
-
-### 0.7.0 (2026-09-28)
-- Add: **OpenCode 2 (beta) plugin compatibility** — the plugin module is dual-shaped
-  (`{id, setup}` for V2 hosts, frozen V1 `server()`), sharing the pre-spawn
-  allowlist/`--yes` gates and the 0.5.1 identity handshake across both shapes;
-  refusal/handshake/rendering byte-parity between edges is pinned by
-  `test/opencode.v2shape.test.ts` while the V1 path stays 16/16 on unmodified
-  tests. Root `index.ts` re-export shipped for V2 directory discovery (which
-  bypasses the exports map; live-proven on `@opencode-ai/cli` beta-19271).
-- Fix: the live V1 probe is anti-vacuous — opting in (`BORDER_OPENCODE_PROBE=1`)
-  without a resolvable binary or built dist now FAILS naming the remedy instead
-  of skipping green-adjacent (`BORDER_OPENCODE_BIN` override added).
-- Docs: support matrix (V1 object entry ≥ 1.18.29; V2 project-local verified;
-  `/border` command V1-only pending the V2 delivery API).
-
-### 0.6.0 (2026-09-25)
-- Add: **the exfil lens** — five rules (`exfil-rfc1918`, `exfil-ssh-target`,
-  `exfil-home-path`, `exfil-cred-location`, `exfil-host-profile`, `exfil-machine-binding`) that flag
-  exfil-shaped literals on about-to-be-public surfaces, the gap classic secret
-  scanners leave open because an internal IP is not a credential. The observed
-  severity of every (rule × facet × channel) cell lives in one machine-readable
-  home, `src/exfil/severity.ts`, rendered — never re-decided — by the check
-  pipeline, the new read-only `border exfil <rev|url>` CLI (tip tree by default,
-  `--deep` history, URL modes into a destroyed temp clone) and the README table,
-  each cell pinned by a docs guard. The tree HIGH family ships as vendored
-  twins (gitleaks TOML + secretlint patterns, ids byte-equal, verdict parity
-  tested); the commit-message facet is native-exclusive with a `:message` id
-  family so allow-list waivers can never cross facets; tag notes stay with the
-  pre-existing `tag-message-secret` engine leg. All exfil sources are
-  fingerprinted into `rulesHash`.
-- Add: **post-push landing verification** — after git legs move, the remote tip
-  is re-observed and scanned with the same machinery; clean appends an
-  append-only `t:"landing"` record and preserves the exit, a blocking hit exits
-  1 ("ALREADY PUBLIC; border detects, never erases"), an unobservable tip exits
-  2 with no record minted. Executed-push rows are never mutated; DRY-RUN lands
-  nothing.
-- Add: **fixture band + assembly doctrine** — 10.200.0.0/16 is reserved as the
-  always-exempt-on-tree test range (exemption mirrored natively in both twins,
-  message facet deliberately not exempt), and the test corpus assembles every
-  other leak shape at runtime (`assembleOctet`/`assembleHost`) so checked-out
-  bytes carry no complete leak tokens: border's own lens is green against
-  border's own corpus. Golden-suite coverage includes an opt-in truth lane
-  (`BORDER_EXFIL_TRUTH=1`) with a documented red-anchor lifetime clause.
-- Note: this release line traces to the 0.5.1 impersonation-wave audit; that
-  wave's H-3 follow-up — scrubbing this repo's own historical tip surfaces —
-  landed here as byte edits with the extracted values withheld from public
-  records by design (see the sanitized `.omo/evidence/` trail, not this log).
-
-### 0.5.1 (2026-09-24)
-- Fix: **plugin impersonation — the `border` tool could spawn the host binary instead of the
-  gate.** On Route B the 0.5.0 adapter resolved its packaged CLI as `process.execPath +
-  dist/index.js`, but inside the opencode plugin host `process.execPath` is the opencode
-  (bun-compiled) binary — sessions saw opencode's banner for `--help` and opencode usage
-  errors for every other command, while the tool's schema still promised border's
-  fail-closed contract. The resolution order is now: `BORDER_BIN` (wins alone; a broken
-  override never silently falls back) → packaged `dist/index.js` exec'd directly via its
-  shebang, else under `PATH` `node` → `border` on `PATH`. `process.execPath` is removed from
-  the adapter, pinned by a source-level regression test, and **every candidate must pass an
-  identity handshake** (`--help` answering with border's banner + `usage: border`, exit 0,
-  20 s cap) before any user argv is spawned — failure reports `cannot-answer` at exit 2 and
-  runs nothing else (spawn failures now map to 2, not 127, aligning the tool with the CLI's
-  exit-code contract). Regression tests cover the unspawnable-override and the
-  opencode-style-impostor fixtures; the impostor logs prove user argv never reaches it.
-  Honest boundary: the handshake catches mistaken identity (host binaries, PATH accidents),
-  not a deliberately forged banner.
-
-### 0.5.0 (2026-09-12)
-- Add: OpenCode plugin adapter (`exports["./server"]` + `/border` + `border` tool) loadable
-  two ways with zero manual install — config-declared `"plugin": ["border-customs@0.5.0"]`
-  (opencode downloads the package; the plugin spawns its own packaged CLI via a
-  package-relative `dist/index.js` resolution, `BORDER_BIN` override, PATH fallback) or
-  `border opencode install` (marker-identified idempotent file drop, foreign files refused,
-  never overwritten). Trigger: an agent session drives the gate without a shell-out or an
-  install ritual; `push --yes` stays terminal-only by design — the tool refuses it.
-
-### 0.4.2 (2026-09-12)
-- Fix: `npm publish` no longer prints the misleading "bin[border] script name
-  dist/index.js was invalid and removed" warning — package.json now carries the
-  canonical bare-relative bin form npm normalizes to anyway (mechanism traced to
-  @npmcli/package-json publish-side; artifacts were never broken; an always-on
-  test locks the form).
-- Change: RubyGems freshness (skip-ledger) parity compares a normalized CONTENT
-  digest instead of raw file bytes — `gem build` stamps the building toolchain
-  (RubyGems <3.6 embeds the build second in gzip headers), so raw-sha repack
-  parity could never be honored on those machines. The ledger digest and the
-  publish-time same-bytes re-hash stay RAW: what gets uploaded is still exactly
-  the certified bytes, and any unparseable artifact fails closed to a full
-  re-check.
-
-### 0.4.1 (2026-09-11)
-- Add: release-coherence rule family — every version source inside a published artifact
-  must agree (pyproject vs MODULE vs filename, gemspec vs gem metadata, Cargo.toml vs
-  crate filename, package.json self-consistency; the git-tag half is a publish-workflow
-  hard gate). Trigger: the aihr incident where a wheel labeled 0.2.2 shipped modules
-  self-reporting 0.2.1 — every pinned consumer silently got old behavior.
-- Add: `border roundtrip` local-artifact input — an argument resolving to an existing
-  file (.whl/.tgz/.crate/.gem, closed table) proves unpublished bytes end-to-end; the
-  streaming sha256 of those exact bytes is the ledger identity and the report carries
-  `source:local:<abs>` provenance. Honest boundary documented: the local PyPI-wheel lane
-  is residue-INERT by construction (pip fully tracks and prunes; verified live on pip
-  24.0 AND 25.0.1) — planted-detection demos belong to the hook-executing lanes
-  (npm postinstall, gem extconf, crates build.rs).
-- Change: pypi roundtrip lane dep-closure calibration — pip's resolver report demotes
-  dependency-storm files to LOW `dep-owned` rows, so genuine orphans stand alone; the
-  demotion requires a legitimate claimant dist-info (pin Name+Version match, canonical
-  dirname, unique, own site-packages root, not the target) after an independent verifier
-  proved a shadow `*-9.9.9.dist-info` could otherwise launder hostile writes.
-
-### 0.4.0 (2026-09-10)
-- Add: `border roundtrip <[ecosystem:]name@version>` — fact-proof valve. Installs the
-  package inside a throwaway Docker container, content-hashes the whole filesystem before
-  and after uninstall, and reports exactly what the uninstaller left behind. Persistence
-  surfaces (rc/profile mutations) => CRITICAL; orphan files => HIGH. Verdicts record to
-  the ledger by default (`--no-record` opts out); Docker absent => fail-closed, never clean.
-- Add: `residue.requireProof` — when on, a residue-capable artifact only passes `border
-  check` with a fresh recorded roundtrip proof (bound to rulesHash; flipping the config
-  invalidates cached verdicts). Missing proof => CRITICAL `roundtrip-proof-missing`.
-- Opt-in test legs: BORDER_ROUNDTRIP_DOCKER=1 (8 real container legs, 4 ecosystems).
-
-### 0.3.2 (2026-09-10)
-- Fix: CLI invoked through the npm `.bin` shim silently exited 0 without running
-  (entrypoint detection now realpath-canonicalizes both sides). Regression-locked by a
-  pack -> install -> shim-invocation test (`BORDER_PACK_TEST=1`, wired into CI).
-- Fix: `publint` is an exact-pinned runtime dependency, so `border scan`/npm checks work
-  out of the box in consumer installs; README documents the engine posture truthfully.
-- Add: release-coherence seed test pinning the scan User-Agent version to package.json.
-
-### 0.3.1 (2026-09-10)
-- Add: `border scan [ecosystem:]name@version` — static residue inspection of third-party
-  registry packages (npm/PyPI/crates.io/RubyGems), ledger-free by design.
-- Docs: README scan section; crates envelope normalization now logs scrubbed-file hashes.
-
-### 0.3.0 (2026-09-09)
-
-- **Residue gate (artifact stage).** The blanket install-hook CRITICAL becomes a classified
-  family of seven closed `residue-*` rules across tiers T1–T4 plus cross-manager, pairing,
-  and gem-unmatched lanes (see "The residue scan"): a hook matching the closed T1 safe-shape
-  signature drops to MEDIUM; every unknown shape keeps the original CRITICAL row verbatim.
-  Pairing (`# BEGIN <id>` marker blocks) is **detected only** — `residue-pairing-missing`
-  fires on the orphaned WRITE, a verified pair still pays its T3 HIGH; the waiver downgrade
-  path is the 0.4.0 roundtrip valve. Detection classes: C5 pairing discipline, C9 indirection
-  spellings, C10 comment/quote boundaries — evidence frozen in `src/artifacts/RESIDUE-CONTRACT.md`.
-- New `residue: { enabled }` config key (default on; strict; the ONLY skip path for the family,
-  and flipping it invalidates cached PASS rows because the toggle rides the fingerprint). The
-  residue rule table and classifier sources are now part of the ledger `rulesHash`: editing a
-  signature forces a re-check even at an unchanged commit and tree.
-- Boundary stated plainly: static analysis proves *capability*, not *fact*; border is not a
-  malware sandbox and never executes what it reads.
-
-### 0.2.0 (2026-09-05)
-
-- Two new push channels, same doctrine end to end: **crates** (public crates.io only;
-  literal `Cargo.toml` coordinates; pre-publish repackage digest-assert) and **rubygems**
-  (rubygems.org or any `targets.rubygems.host` gemcutter-compatible host; literal-only
-  gemspecs; `s.date` rejection).
-- Platforms are now descriptors in a channel registry: each channel owns its config schema,
-  env expansion, coordinate reading, probe, artifact stage, publish argv, and ledger fields
-  in one file. The git/npm/pypi legs share the same publish core they already used; their
-  behavior is unchanged.
-- Ledger `confirmedVia` gained `crates-json` and `rubygems-json`; 0.1.x ledgers parse
-  unchanged.
-- New prerequisites when those targets are configured: `cargo` on `PATH` (measured against
-  1.93.1 via rustup) and `gem` (measured against RubyGems 3.6.7 on ruby 3.3.8); other
-  versions are untested by the gate's same-bytes proofs.
-
-### 0.1.0
-
-- Initial release: git, npm, and PyPI push channels behind the fingerprint PASS gate.
+Full per-version history with the motivating incident for each release:
+[CHANGELOG.md](CHANGELOG.md). Release receipts (build provenance, gate transcripts):
+[docs/release/](docs/release/).
 
 ## License
 

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "border-customs",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "border-customs",
-      "version": "0.8.3",
+      "version": "0.8.5",
       "license": "MIT",
       "dependencies": {
         "@secretlint/core": "13.0.5",

package/dist/index.js

@@ -44,7 +44,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var define_BORDER_BUILD_default;
 var init_define_BORDER_BUILD = __esm({
   "<define:__BORDER_BUILD__>"() {
-    define_BORDER_BUILD_default = { version: "0.8.3", commit: "5f2f4c31d43916bed00a3c5b3448b3f377af4c23", dirty: false, builtAt: "2026-11-02T05:02:18.524Z" };
+    define_BORDER_BUILD_default = { version: "0.8.5", commit: "56c5aa3959e18fa143e49904608f4564798ff0a6", dirty: false, builtAt: "2026-11-08T08:34:50.133Z" };
   }
 });
 
@@ -30368,8 +30368,8 @@ function sandboxBindingJoin(images) {
   return [...new Set(images)].sort().join("\n");
 }
 function sandboxRun(o) {
-  const probe = o.laneProbes.map((p) => `{ printf '%s ' '${p}'; ${p} --version 2>&1 | head -n 1; }`).join("\n");
-  const script = `${probe} > /audit/out/toolchain.txt
+  const probe2 = o.laneProbes.map((p) => `{ printf '%s ' '${p}'; ${p} --version 2>&1 | head -n 1; }`).join("\n");
+  const script = `${probe2} > /audit/out/toolchain.txt
 ${o.laneScript}`;
   const r = runSandboxedBuild({
     spec: o.spec,
@@ -37531,8 +37531,8 @@ function pypiArtifactCoherenceFindings(o) {
   for (const initRel of o.files.filter((f) => /(?:^|\/)__init__\.py$/.test(f)).sort()) {
     const body = o.read(initRel);
     if (body === null) continue;
-    const probe = probeDunderVersion(body);
-    if (probe !== null) sources.push({ label: `__version__ literal in ${initRel}`, path: initRel, probe });
+    const probe2 = probeDunderVersion(body);
+    if (probe2 !== null) sources.push({ label: `__version__ literal in ${initRel}`, path: initRel, probe: probe2 });
   }
   const hits = [];
   analyze(sources, `${o.archiveName}!`, hits);
@@ -37978,6 +37978,29 @@ init_define_BORDER_BUILD();
 import { spawnSync as spawnSync6 } from "node:child_process";
 import { dirname as dirname6, resolve as resolve6 } from "node:path";
 
+// src/lsremote.ts
+init_define_BORDER_BUILD();
+var PushStateError = class extends Error {
+  exitCode = 2;
+  name = "PushStateError";
+};
+var SHA_SHAPE = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/;
+function parseLsRemote(text, targetId) {
+  const out = /* @__PURE__ */ new Map();
+  for (const line of text.split("\n")) {
+    if (line.trim() === "") continue;
+    const fields = line.split("	");
+    const sha = fields[0];
+    const ref = fields[1];
+    const shapeOk = fields.length === 2 && sha !== void 0 && SHA_SHAPE.test(sha) && (ref === "HEAD" || ref !== void 0 && ref.startsWith("refs/"));
+    if (!shapeOk) {
+      throw new PushStateError(`target '${targetId}': malformed 'git ls-remote' output line '${line.slice(0, 72)}' \u2014 refusing to interpret (fail closed)`);
+    }
+    if (ref !== "HEAD") out.set(ref, sha);
+  }
+  return out;
+}
+
 // src/rules/allowlist.ts
 init_define_BORDER_BUILD();
 var BOT_EMAIL_PATTERN = "*[bot]@users.noreply.github.com";
@@ -38055,7 +38078,6 @@ function runGit2(repoDir, args) {
 }
 var LOG_FIELDS = 6;
 var LOG_FORMAT = "--format=%H%x1f%an%x1f%ae%x1f%cn%x1f%ce%x1f%P";
-var REV_BATCH = 200;
 function collectCommits(s, revs) {
   const out = runGit2(s.repoDir, ["log", LOG_FORMAT, ...revs]);
   for (const line of out.split("\n")) {
@@ -38094,30 +38116,66 @@ function revExists(repoDir, rev) {
   });
   return r.status === 0;
 }
-function trackingEndpoint(repoDir, remoteName, ref) {
-  const candidates = [`refs/remotes/${remoteName}/${ref}`];
-  const short = ref.replace(/^refs\/(?:heads|tags)\//, "");
-  if (short !== ref) candidates.push(`refs/remotes/${remoteName}/${short}`);
-  return candidates.find((c) => revExists(repoDir, c)) ?? null;
+function revParse(repoDir, rev) {
+  return runGit2(repoDir, ["rev-parse", rev]).trim();
 }
-function scanTransmitted(s, refSet, remotes) {
-  const names = remotes.map((r) => r.name).filter((n) => n !== void 0);
-  if (names.length === 0) return;
-  for (const ref of refSet) {
-    if (!revExists(s.repoDir, ref)) continue;
-    for (const name of names) {
-      const endpoint = trackingEndpoint(s.repoDir, name, ref);
-      if (endpoint === null) continue;
-      const out = runGit2(s.repoDir, ["rev-list", `${endpoint}..${ref}`]);
-      const fresh = [];
-      for (const sha of out.split("\n")) {
-        if (sha !== "" && !s.seen.has(sha)) fresh.push(sha);
+var LS_REMOTE_TIMEOUT_MS = 3e4;
+function urlForMessage(url2) {
+  try {
+    const u = new URL(url2);
+    if (u.protocol === "file:") return url2;
+    return `${u.protocol}//${u.host}/***`;
+  } catch {
+    return "***";
+  }
+}
+function lsRemoteFetch(repoDir, url2, env2) {
+  const r = spawnSync6("git", ["ls-remote", url2], {
+    cwd: repoDir,
+    encoding: "utf8",
+    env: { ...process.env, ...env2, GIT_CEILING_DIRECTORIES: dirname6(resolve6(repoDir)) },
+    timeout: LS_REMOTE_TIMEOUT_MS
+  });
+  if (r.error !== void 0 || r.status !== 0) {
+    const why = r.error !== void 0 ? r.error.message : (r.stderr ?? "").trim().slice(-200);
+    throw new Error(
+      `identity: remote ${urlForMessage(url2)} is unreachable via git ls-remote (${why}) \u2014 the exposure class of the offending identities cannot be decided and border never guesses it; restore connectivity or scope the check and retry`
+    );
+  }
+  return parseLsRemote(r.stdout ?? "", urlForMessage(url2));
+}
+function remoteTruth(o, walkShas) {
+  const truth = { published: /* @__PURE__ */ new Set(), publishedTags: /* @__PURE__ */ new Set(), remoteLabels: [] };
+  const resolvable = o.refSet.filter((ref) => revExists(o.repoDir, ref));
+  const urls = [...new Set(o.cfg.targets.git.remotes.map((r) => r.url).filter((u) => u !== void 0 && u.length > 0))];
+  if (resolvable.length === 0 || urls.length === 0) return truth;
+  const env2 = o.env ?? process.env;
+  const fetch2 = o.lsRemote ?? ((url2) => lsRemoteFetch(o.repoDir, url2, env2));
+  for (const url2 of urls) {
+    const map2 = fetch2(url2);
+    truth.remoteLabels.push(urlForMessage(url2));
+    for (const ref of resolvable) {
+      const ep = map2.get(ref) ?? map2.get(`${ref}^{}`);
+      if (ep === void 0) continue;
+      if (!/^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(ep)) {
+        throw new Error(`identity: remote ${urlForMessage(url2)} reports a malformed endpoint sha for ${ref} \u2014 refusing to interpret (fail closed)`);
+      }
+      if (ref.startsWith("refs/tags/")) {
+        const localObj = revParse(o.repoDir, ref);
+        const localPeel = revParse(o.repoDir, `${ref}^{}`);
+        if (map2.get(ref) === localObj || map2.get(`${ref}^{}`) === localPeel) truth.publishedTags.add(ref);
+        continue;
       }
-      for (let i = 0; i < fresh.length; i += REV_BATCH) {
-        collectCommits(s, ["--no-walk", ...fresh.slice(i, i + REV_BATCH)]);
+      if (!revExists(o.repoDir, ep)) {
+        throw new Error(
+          `identity: remote ${urlForMessage(url2)} points ${ref} at ${ep.slice(0, 12)}, which is not an object in this repository \u2014 the transmitted set cannot be computed; run 'git fetch ${urlForMessage(url2)}' and retry (fail closed)`
+        );
       }
+      const fresh = new Set(runGit2(o.repoDir, ["rev-list", `${ep}..${ref}`]).split("\n").filter((s) => s !== ""));
+      for (const sha of walkShas) if (!fresh.has(sha)) truth.published.add(sha);
     }
   }
+  return truth;
 }
 function scanTags(repoDir, authors) {
   const entries = /* @__PURE__ */ new Map();
@@ -38155,35 +38213,61 @@ function mergeEntries(target, extra) {
     }
   }
 }
+var IDENTITY_PUBLIC_RULE = "identity-already-public";
+function locationsSuffix(objects) {
+  const locations = objects.map(([obj, roles]) => `${roles} of ${obj}`);
+  const shownList = locations.slice(0, MAX_LISTED_LOCATIONS);
+  const more = locations.length - shownList.length;
+  return { shown: shownList.join("; "), suffix: more > 0 ? ` (+${String(more)} more)` : "" };
+}
 function scanIdentity(o) {
   const authors = o.cfg.rules.authors;
   const s = { repoDir: o.repoDir, authors, entries: /* @__PURE__ */ new Map(), seen: /* @__PURE__ */ new Set() };
-  if (o.refSet.length > 0) {
-    collectCommits(s, o.refSet);
-    scanTransmitted(s, o.refSet, o.cfg.targets.git.remotes);
-  }
+  if (o.refSet.length > 0) collectCommits(s, o.refSet);
   mergeEntries(s.entries, scanTags(o.repoDir, authors));
+  const truth = s.entries.size > 0 ? remoteTruth(o, s.seen) : { published: /* @__PURE__ */ new Set(), publishedTags: /* @__PURE__ */ new Set(), remoteLabels: [] };
   const findings = [];
   for (const entry of s.entries.values()) {
-    const locations = [...entry.objects].map(([obj, roles]) => `${roles} of ${obj}`);
-    const shown = locations.slice(0, MAX_LISTED_LOCATIONS);
-    const more = locations.length - shown.length;
-    const suffix = more > 0 ? ` (+${String(more)} more)` : "";
+    const freshObjects = [];
+    const publicObjects = [];
+    for (const [obj, roles] of entry.objects) {
+      const isCommit = /^[0-9a-f]{40}$/.test(obj);
+      const published = isCommit ? truth.published.has(obj) : truth.publishedTags.has(obj);
+      (published ? publicObjects : freshObjects).push([obj, roles]);
+    }
     const identity = `${entry.name} <${entry.email}>`;
-    const firstCommit = [...entry.objects.entries()].find(([obj]) => /^[0-9a-f]{40}$/.test(obj));
     const { valueDigest, snippet } = redact(identity);
-    const raw = `'${identity}' is not allowlisted in rules.authors \u2014 push would expose this git identity forever: ${shown.join("; ")}${suffix}. Remediation: use git filter-repo manually (out of scope for border; border never rewrites history).`;
-    const finding = {
-      rule: IDENTITY_RULE,
-      severity: "CRITICAL",
-      target: IDENTITY_TARGET,
-      engine: IDENTITY_ENGINE,
-      message: o.sanitizer?.sanitize(raw) ?? raw,
-      valueDigest,
-      snippet
-    };
-    if (firstCommit !== void 0) finding.commit = firstCommit[0];
-    findings.push(finding);
+    const firstCommit = [...freshObjects, ...publicObjects].find(([obj]) => /^[0-9a-f]{40}$/.test(obj));
+    if (freshObjects.length > 0) {
+      const { shown, suffix } = locationsSuffix(freshObjects);
+      const raw = `'${identity}' is not allowlisted in rules.authors \u2014 push would expose this git identity forever: ${shown}${suffix}. Remediation: use git filter-repo manually (out of scope for border; border never rewrites history).`;
+      const finding = {
+        rule: IDENTITY_RULE,
+        severity: "CRITICAL",
+        target: IDENTITY_TARGET,
+        engine: IDENTITY_ENGINE,
+        message: o.sanitizer?.sanitize(raw) ?? raw,
+        valueDigest,
+        snippet
+      };
+      if (firstCommit !== void 0) finding.commit = firstCommit[0];
+      findings.push(finding);
+    }
+    if (publicObjects.length > 0) {
+      const { shown, suffix } = locationsSuffix(publicObjects);
+      const raw = `'${identity}' is not allowlisted in rules.authors \u2014 but every object carrying it is already public on the configured remote(s) (${truth.remoteLabels.join(", ") || "remotes probed"}): ${shown}${suffix}. Nothing new leaves this machine with this push; recorded as fact for housekeeping (add it to rules.authors, or keep it out of new commits). border detects, never erases \u2014 rewriting published history is not offered.`;
+      const publishedFinding = {
+        rule: IDENTITY_PUBLIC_RULE,
+        severity: "INFO",
+        target: IDENTITY_TARGET,
+        engine: IDENTITY_ENGINE,
+        message: o.sanitizer?.sanitize(raw) ?? raw,
+        valueDigest: redact(`${identity}:already-public`).valueDigest,
+        snippet
+      };
+      if (firstCommit !== void 0) publishedFinding.commit = firstCommit[0];
+      findings.push(publishedFinding);
+    }
   }
   return findings;
 }
@@ -39404,12 +39488,12 @@ function pruneRunDirs(repoDir, key8, keep = KEEP_RUN_DIRS_PER_KEY8) {
 async function computeFingerprint(repoDir, cfg, configDigest, effectiveTargets, o = {}) {
   const envOpt = o.env !== void 0 ? { env: o.env } : {};
   const ctx = await gatherContext(repoDir, envOpt);
-  const probe = await probeEngines(cfg, {
+  const probe2 = await probeEngines(cfg, {
     ...envOpt,
     ...o.requireOverride !== void 0 ? { requireOverride: o.requireOverride } : {}
   });
   const rulesHash = await computeCheckRulesHash({
-    engineVersions: probe.engineVersions,
+    engineVersions: probe2.engineVersions,
     configDigest,
     ...envOpt
   });
@@ -39425,7 +39509,7 @@ async function computeFingerprint(repoDir, cfg, configDigest, effectiveTargets,
     rulesHash,
     exposureSet: [...exposureSet(cfg, { cwd: repoDir })]
   };
-  return { ctx, fp, probeDegraded: probe.degraded };
+  return { ctx, fp, probeDegraded: probe2.degraded };
 }
 async function consultSkipLedger(q) {
   let ctx;
@@ -40156,26 +40240,6 @@ function gitTargetId(remote, index) {
 }
 
 // src/pushstate.ts
-var PushStateError = class extends Error {
-  exitCode = 2;
-  name = "PushStateError";
-};
-var SHA_SHAPE = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/;
-function parseLsRemote(text, targetId) {
-  const out = /* @__PURE__ */ new Map();
-  for (const line of text.split("\n")) {
-    if (line.trim() === "") continue;
-    const fields = line.split("	");
-    const sha = fields[0];
-    const ref = fields[1];
-    const shapeOk = fields.length === 2 && sha !== void 0 && SHA_SHAPE.test(sha) && (ref === "HEAD" || ref !== void 0 && ref.startsWith("refs/"));
-    if (!shapeOk) {
-      throw new PushStateError(`target '${targetId}': malformed 'git ls-remote' output line '${line.slice(0, 72)}' \u2014 refusing to interpret (fail closed)`);
-    }
-    if (ref !== "HEAD") out.set(ref, sha);
-  }
-  return out;
-}
 function localRefCommits(repoDir, refSet, env2) {
   const commits = /* @__PURE__ */ new Map();
   if (refSet.length === 0) return commits;
@@ -42332,6 +42396,46 @@ function resolveBuildConsent(o) {
   return { allowed: false, reason: WITHHELD_REASON };
 }
 
+// src/check/ignoredSurface.ts
+init_define_BORDER_BUILD();
+var IGNORED_SURFACE_NOTE = " \u2014 path is .gitignore'd and untracked: git add honours .gitignore, so it cannot reach a push; informational surface, never blocking";
+function nulList(stdout) {
+  return new Set(stdout.split("\0").filter((p) => p !== ""));
+}
+function ignoredHit(rel, ignored) {
+  if (ignored.has(rel)) return true;
+  let cut = rel.indexOf("/");
+  while (cut > 0) {
+    if (ignored.has(`${rel.slice(0, cut)}/`)) return true;
+    cut = rel.indexOf("/", cut + 1);
+  }
+  return false;
+}
+function relFacetPath(f, repoDir) {
+  if (f.path === void 0 || f.commit !== void 0) return null;
+  if (f.target !== "git" && f.target !== "tree") return null;
+  const outer = f.path.split("!")[0] ?? f.path;
+  const prefix = `${repoDir}/`;
+  return outer.startsWith(prefix) ? outer.slice(prefix.length) : outer;
+}
+function demoteIgnoredUntracked(findings, repoDir, o = {}) {
+  const candidates = findings.filter((f) => f.severity !== "INFO" && relFacetPath(f, repoDir) !== null);
+  if (candidates.length === 0) return 0;
+  const tracked = nulList(runGitChecked(repoDir, ["ls-files", "-z"], o));
+  const ignored = nulList(runGitChecked(repoDir, ["ls-files", "--others", "--ignored", "--exclude-standard", "-z"], o));
+  if (ignored.size === 0) return 0;
+  let demoted = 0;
+  for (const f of findings) {
+    if (f.severity === "INFO") continue;
+    const rel = relFacetPath(f, repoDir);
+    if (rel === null || !ignoredHit(rel, ignored) || tracked.has(rel)) continue;
+    f.severity = "INFO";
+    f.message = `${f.message}${IGNORED_SURFACE_NOTE}`;
+    demoted += 1;
+  }
+  return demoted;
+}
+
 // src/check/exfilTreeScan.ts
 init_define_BORDER_BUILD();
 import { readFileSync as readFileSync17, statSync as statSync2 } from "node:fs";
@@ -42583,7 +42687,7 @@ function revExists2(run2, rev) {
     return false;
   }
 }
-function trackingEndpoint2(run2, remoteName, ref) {
+function trackingEndpoint(run2, remoteName, ref) {
   const candidates = [`refs/remotes/${remoteName}/${ref}`];
   const short = ref.replace(/^refs\/(?:heads|tags)\//, "");
   if (short !== ref) candidates.push(`refs/remotes/${remoteName}/${short}`);
@@ -42606,7 +42710,7 @@ function willPublishShas(run2, refSet, remotes) {
     for (const remote of remotes) {
       const name = remote.name;
       if (name === void 0) continue;
-      const endpoint = trackingEndpoint2(run2, name, ref);
+      const endpoint = trackingEndpoint(run2, name, ref);
       if (endpoint !== null) ranges.push(`${endpoint}..${ref}`);
     }
     if (ranges.length === 0) collect([ref]);
@@ -43136,13 +43240,13 @@ async function runPipeline(o, ctx, lockWarning) {
   const envOpt = o.env !== void 0 ? { env: o.env } : {};
   const findings = [];
   const guard = trackedBorderStateFinding(repoDir, ctx.headSha, o.env);
-  const probe = await probeEngines(o.cfg, {
+  const probe2 = await probeEngines(o.cfg, {
     ...envOpt,
     ...o.requireOverride !== void 0 ? { requireOverride: o.requireOverride } : {}
   });
-  findings.push(...probe.findings);
+  findings.push(...probe2.findings);
   if (guard !== null) findings.push(guard);
-  const broken = new Set(probe.findings.map((f) => f.engine));
+  const broken = new Set(probe2.findings.map((f) => f.engine));
   const sanitizer = new TextSanitizer();
   findings.push(...filterBorderStateFindings(detectHostileConfig({ repoDir, target: "git", ...envOpt }), repoDir));
   if (!broken.has("gitleaks")) {
@@ -43187,6 +43291,7 @@ async function runPipeline(o, ctx, lockWarning) {
       findings.push(f);
     }
   }
+  demoteIgnoredUntracked(findings, repoDir, o.env !== void 0 ? { env: o.env } : {});
   const ledgerArtifacts = [];
   const buildToolchains = [];
   for (const channel of publishChannels()) {
@@ -43235,7 +43340,7 @@ async function runPipeline(o, ctx, lockWarning) {
     }
   }
   const rulesHash = await computeCheckRulesHash({
-    engineVersions: probe.engineVersions,
+    engineVersions: probe2.engineVersions,
     configDigest: o.configDigest,
     ...o.env !== void 0 ? { env: o.env } : {}
   });
@@ -43295,7 +43400,7 @@ async function runPipeline(o, ctx, lockWarning) {
   return {
     report,
     ctx,
-    degraded: probe.degraded,
+    degraded: probe2.degraded,
     sanitizedSummary: sanitizeSummary(report, sanitizer),
     lockWarning,
     artifacts: ledgerArtifacts.length > 0 ? ledgerArtifacts : null,
@@ -43326,12 +43431,12 @@ async function runCheck(ctx) {
     effective = { kind: "loaded", config: load.explicit.config, warnings: [], source: load.explicit.source, security: load.explicit.security };
   } else {
     if (ctx.flags.requireEngine !== void 0 && ctx.flags.requireEngine.length > 0) {
-      const probe = await probeEngines(NO_TARGETS_PROBE_CFG, {
+      const probe2 = await probeEngines(NO_TARGETS_PROBE_CFG, {
         requireOverride: ctx.flags.requireEngine,
         ...env2 !== void 0 ? { env: env2 } : {}
       });
-      if (probe.degraded) {
-        for (const finding of probe.findings) ctx.stderr(`border: ${finding.message}`);
+      if (probe2.degraded) {
+        for (const finding of probe2.findings) ctx.stderr(`border: ${finding.message}`);
         return EXIT_ERROR;
       }
     }
@@ -43849,13 +43954,13 @@ async function runLlmRequest(ctx) {
 
 // src/commands/opencode.ts
 init_define_BORDER_BUILD();
-import { existsSync as existsSync23, lstatSync, mkdirSync as mkdirSync12, readFileSync as readFileSync23, rmSync as rmSync14, writeFileSync as writeFileSync8 } from "node:fs";
+import { existsSync as existsSync24, lstatSync, mkdirSync as mkdirSync12, readFileSync as readFileSync23, rmSync as rmSync14, writeFileSync as writeFileSync8 } from "node:fs";
 import { dirname as dirname17, join as join36 } from "node:path";
 import { fileURLToPath as fileURLToPath7 } from "node:url";
 
 // src/opencode/inspect.ts
 init_define_BORDER_BUILD();
-import { existsSync as existsSync22, readFileSync as readFileSync22 } from "node:fs";
+import { existsSync as existsSync23, readFileSync as readFileSync22 } from "node:fs";
 import { join as join35 } from "node:path";
 
 // src/opencode/aspects/cacheVersion.ts
@@ -44105,6 +44210,10 @@ function verifyDualRoute(facts) {
   return { id, verdict: "PASS", detail: "neither route registered \u2014 no border plugin load claimed on the V1 surface" };
 }
 
+// src/opencode/aspects/globalResolution.ts
+init_define_BORDER_BUILD();
+import { existsSync as existsSync22 } from "node:fs";
+
 // src/opencode/aspects/identity.ts
 init_define_BORDER_BUILD();
 import { execFile } from "node:child_process";
@@ -44161,11 +44270,11 @@ async function verifyIdentity(deps) {
   const reasons = [];
   let anySpawned = false;
   for (const candidate of candidates) {
-    const probe = await runner(candidate, HANDSHAKE_ARGV);
-    if (passesHandshake(probe)) {
+    const probe2 = await runner(candidate, HANDSHAKE_ARGV);
+    if (passesHandshake(probe2)) {
       return { id, verdict: "PASS", detail: `${candidate.label} passed the identity handshake` };
     }
-    if (probe.status !== null) {
+    if (probe2.status !== null) {
       anySpawned = true;
       reasons.push(`${candidate.label}: spawned but --help did not answer as border (impostor?)`);
     } else {
@@ -44178,51 +44287,6 @@ async function verifyIdentity(deps) {
   return { id, verdict: "CANNOT", detail: `no border binary reachable \u2014 tried: ${reasons.join("; ")}` };
 }
 
-// src/opencode/aspects/routeA.ts
-init_define_BORDER_BUILD();
-function verifyRouteAParity(facts) {
-  const id = "route-a-parity";
-  const { routeAPlugin, routeAInstalled } = facts;
-  if (!routeAInstalled) {
-    return { id, verdict: "PASS", detail: `${routeAPlugin}: absent \u2014 Route A not installed, nothing to be stale` };
-  }
-  if (facts.packagedPlugin === null) {
-    return { id, verdict: "CANNOT", detail: "the packaged plugin asset is unreadable \u2014 the border install itself looks broken, parity cannot be judged" };
-  }
-  const installed = facts.routeABytes;
-  if (installed === null) {
-    return { id, verdict: "CANNOT", detail: `${routeAPlugin}: present but unreadable \u2014 parity cannot be judged` };
-  }
-  const installedSha = sha256Hex3(installed);
-  const packagedSha = sha256Hex3(facts.packagedPlugin);
-  if (installedSha === packagedSha) {
-    return { id, verdict: "PASS", detail: `${routeAPlugin}: up-to-date installed=${installedSha} packaged=${packagedSha}` };
-  }
-  const ours = firstLine(installed).startsWith(PLUGIN_MARKER);
-  const shape = ours ? "outdated (marker ours, bytes differ)" : "foreign (first line lacks the marker)";
-  return { id, verdict: "FAIL", detail: `${routeAPlugin}: ${shape} installed=${installedSha} packaged=${packagedSha}` };
-}
-
-// src/opencode/aspects/scope.ts
-init_define_BORDER_BUILD();
-var SCOPE_ID = "scope";
-var SCOPE_NAME = "v1-load-surface";
-var SCOPE_UNCOVERED = [
-  "V2 project-local .opencode/plugins/",
-  "V2 npm-prefix/node_modules installs",
-  "V2 lazy activation state"
-];
-function verifyScope() {
-  return {
-    id: SCOPE_ID,
-    verdict: "PASS",
-    detail: `verdict scope = ${SCOPE_NAME}; NOT covered (declared blind, separate ledger item): ${SCOPE_UNCOVERED.join(", ")}`
-  };
-}
-
-// src/opencode/aspects/specFreshness.ts
-init_define_BORDER_BUILD();
-
 // src/opencode/registry.ts
 init_define_BORDER_BUILD();
 var isRecord3 = (v) => typeof v === "object" && v !== null;
@@ -44276,7 +44340,110 @@ async function fetchRegistryVersion(fetcher, url2, timeoutMs) {
   return parsed["version"];
 }
 
+// src/opencode/aspects/globalResolution.ts
+var VERSION_ARGV = ["--version"];
+function parseVersionStamp(stdout) {
+  const m = /^border\s+(\d[^\s]*)/m.exec(stdout);
+  return m?.[1] ?? null;
+}
+async function probe(runner, target) {
+  const out = await runner(target, VERSION_ARGV);
+  if (out.status === null) return "unspawnable";
+  return parseVersionStamp(out.stdout) ?? "no version stamp";
+}
+async function verifyGlobalResolution(deps) {
+  const id = "global-resolution";
+  if ((deps.env["BORDER_INSPECT_OFFLINE"] ?? "") === "1") {
+    return { id, verdict: "WARN", detail: "skipped (BORDER_INSPECT_OFFLINE=1) \u2014 freshness not evaluated; an unevaluated face is never reported as fresh" };
+  }
+  const runner = deps.runner ?? defaultInspectRunner;
+  const override = deps.env["BORDER_BIN"];
+  const hasOverride = override !== void 0 && override.length > 0;
+  const faces = [];
+  let active = null;
+  if (hasOverride) {
+    const stamp = await probe(runner, { bin: override, prefix: [], label: `BORDER_BIN=${override}` });
+    faces.push({ label: `env BORDER_BIN=${override}`, stamp });
+    active = stamp;
+  } else {
+    if (existsSync22(deps.distEntry)) {
+      const packaged = { bin: deps.distEntry, prefix: [], label: "packaged dist" };
+      let stamp = await probe(runner, packaged);
+      if (stamp === "unspawnable") {
+        stamp = await probe(runner, { bin: "node", prefix: [deps.distEntry], label: "packaged dist" });
+      }
+      faces.push({ label: "packaged dist", stamp });
+    }
+    const pathStamp = await probe(runner, { bin: "border", prefix: [], label: "border on PATH" });
+    faces.push({ label: "border on PATH", stamp: pathStamp });
+    active = pathStamp === "unspawnable" ? null : pathStamp;
+  }
+  const faceLine = faces.map((f) => `${f.label}: ${f.stamp}`).join("; ");
+  const fetcher = deps.fetcher ?? defaultRegistryFetcher;
+  let latest;
+  try {
+    latest = await fetchRegistryVersion(fetcher, npmTagUrl(deps.pkg, "latest", deps.registryBase), deps.timeoutMs ?? REGISTRY_TIMEOUT_MS2);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { id, verdict: "CANNOT", detail: `registry unreachable for global-resolution: ${message}; ${faceLine}` };
+  }
+  if (active === null) {
+    return { id, verdict: "PASS", detail: `no active CLI face (no BORDER_BIN, no PATH border); registry latest ${latest}; ${faceLine}` };
+  }
+  const activeCore = active.split("+")[0];
+  if (activeCore === latest) {
+    return { id, verdict: "PASS", detail: `active face matches registry latest ${latest}; ${faceLine}` };
+  }
+  if (active === "unspawnable" || active === "no version stamp") {
+    return { id, verdict: "WARN", detail: `active CLI face carries no version stamp (registry latest ${latest}) \u2014 informational: identity may be fine, age is unknown; ${faceLine}` };
+  }
+  return { id, verdict: "WARN", detail: `active CLI face is ${active}, registry latest is ${latest} \u2014 informational only: pinned consumption is a legitimate steady state, the decision to update stays with the human; ${faceLine}` };
+}
+
+// src/opencode/aspects/routeA.ts
+init_define_BORDER_BUILD();
+function verifyRouteAParity(facts) {
+  const id = "route-a-parity";
+  const { routeAPlugin, routeAInstalled } = facts;
+  if (!routeAInstalled) {
+    return { id, verdict: "PASS", detail: `${routeAPlugin}: absent \u2014 Route A not installed, nothing to be stale` };
+  }
+  if (facts.packagedPlugin === null) {
+    return { id, verdict: "CANNOT", detail: "the packaged plugin asset is unreadable \u2014 the border install itself looks broken, parity cannot be judged" };
+  }
+  const installed = facts.routeABytes;
+  if (installed === null) {
+    return { id, verdict: "CANNOT", detail: `${routeAPlugin}: present but unreadable \u2014 parity cannot be judged` };
+  }
+  const installedSha = sha256Hex3(installed);
+  const packagedSha = sha256Hex3(facts.packagedPlugin);
+  if (installedSha === packagedSha) {
+    return { id, verdict: "PASS", detail: `${routeAPlugin}: up-to-date installed=${installedSha} packaged=${packagedSha}` };
+  }
+  const ours = firstLine(installed).startsWith(PLUGIN_MARKER);
+  const shape = ours ? "outdated (marker ours, bytes differ)" : "foreign (first line lacks the marker)";
+  return { id, verdict: "FAIL", detail: `${routeAPlugin}: ${shape} installed=${installedSha} packaged=${packagedSha}` };
+}
+
+// src/opencode/aspects/scope.ts
+init_define_BORDER_BUILD();
+var SCOPE_ID = "scope";
+var SCOPE_NAME = "v1-load-surface";
+var SCOPE_UNCOVERED = [
+  "V2 project-local .opencode/plugins/",
+  "V2 npm-prefix/node_modules installs",
+  "V2 lazy activation state"
+];
+function verifyScope() {
+  return {
+    id: SCOPE_ID,
+    verdict: "PASS",
+    detail: `verdict scope = ${SCOPE_NAME}; NOT covered (declared blind, separate ledger item): ${SCOPE_UNCOVERED.join(", ")}`
+  };
+}
+
 // src/opencode/aspects/specFreshness.ts
+init_define_BORDER_BUILD();
 var isExactVersion2 = (spec) => /^\d+\.\d+\.\d+([-+].*)?$/.test(spec);
 async function verifySpecFreshness(facts, deps = {}) {
   const id = "spec-freshness";
@@ -44333,6 +44500,7 @@ function inspectExit(verdict) {
     case "CANNOT":
       return EXIT_ERROR;
     case "PASS":
+    case "WARN":
       return EXIT_PASS;
   }
 }
@@ -44348,7 +44516,7 @@ function gatherFacts(env2, cwd, deps) {
   const pluginDrop = routeAPluginPath(env2);
   const cacheRoot = deps.cacheRoot ?? opencodeCacheRoot(env2);
   const globalPath = deps.globalConfigPath ?? join35(opencodeConfigRoot(env2), "opencode", "opencode.jsonc");
-  const routeAInstalled = existsSync22(pluginDrop);
+  const routeAInstalled = existsSync23(pluginDrop);
   return {
     pkg,
     env: env2,
@@ -44363,6 +44531,7 @@ function gatherFacts(env2, cwd, deps) {
 }
 async function runInspectCore(ctx, deps = {}) {
   const facts = gatherFacts(ctx.env, ctx.cwd, deps);
+  const distEntry = deps.distEntry ?? packagedDistEntry(import.meta.url);
   const aspects = [
     verifyCacheVersion(facts),
     await verifySpecFreshness(facts, {
@@ -44371,12 +44540,20 @@ async function runInspectCore(ctx, deps = {}) {
     }),
     await verifyIdentity({
       ...deps.runner !== void 0 ? { runner: deps.runner } : {},
-      distEntry: deps.distEntry ?? packagedDistEntry(import.meta.url),
+      distEntry,
       env: facts.env
     }),
     verifyRouteAParity(facts),
     verifyDualRoute(facts),
-    verifyScope()
+    verifyScope(),
+    await verifyGlobalResolution({
+      ...deps.runner !== void 0 ? { runner: deps.runner } : {},
+      distEntry,
+      env: facts.env,
+      pkg: facts.pkg,
+      ...deps.registryFetcher !== void 0 ? { fetcher: deps.registryFetcher } : {},
+      ...deps.registryBase !== void 0 ? { registryBase: deps.registryBase } : {}
+    })
   ];
   const verdict = aggregateVerdict(aspects);
   const report = { schemaVersion: 1, scope: "v1", verdict, aspects };
@@ -44400,7 +44577,7 @@ function resolvePluginAsset(moduleUrl, fileName) {
     join36(here, "..", "..", "plugin", fileName)
     // src mode: <root>/plugin/<f>
   ];
-  return candidates.find((p) => existsSync23(p)) ?? candidates[1];
+  return candidates.find((p) => existsSync24(p)) ?? candidates[1];
 }
 function targetsFor(env2) {
   const root = join36(opencodeConfigRoot(env2), "opencode");
@@ -44972,7 +45149,7 @@ import { createHash as createHash20 } from "node:crypto";
 import { basename as basename5 } from "node:path";
 var SCAN_MAX_ARTIFACT_BYTES = 200 * 1024 * 1024;
 var SCAN_REQUEST_TIMEOUT_MS = 6e4;
-var SCAN_USER_AGENT = "border-customs/0.8.3 (+https://github.com/TachikomaGundam/Border-Customs; border scan)";
+var SCAN_USER_AGENT = "border-customs/0.8.5 (+https://github.com/TachikomaGundam/Border-Customs; border scan)";
 var CRATES_DOWNLOAD_HOST = "https://static.crates.io";
 var defaultScanFetcher = async (url2, init) => {
   if (!/^https?:\/\//.test(url2)) throw new EngineRunError(`border scan refuses non-http(s) URL: ${url2}`, null);
@@ -45143,7 +45320,7 @@ function parseScanSpec(raw) {
 
 // src/roundtrip/localArtifact.ts
 init_define_BORDER_BUILD();
-import { createReadStream, existsSync as existsSync24, statSync as statSync3 } from "node:fs";
+import { createReadStream, existsSync as existsSync25, statSync as statSync3 } from "node:fs";
 import { createHash as createHash21 } from "node:crypto";
 import { basename as basename6, resolve as resolve20 } from "node:path";
 var EXT_TABLE = /* @__PURE__ */ new Map([
@@ -45192,7 +45369,7 @@ var GRAMMAR_HINT = {
 };
 function classifyLocalInput(raw, cwd, parsesAsRegistrySpec) {
   const abs = resolve20(cwd, raw);
-  if (existsSync24(abs)) {
+  if (existsSync25(abs)) {
     const st = statSync3(abs);
     if (st.isDirectory()) {
       bad3(`'${raw}' resolves to a directory (${abs}) \u2014 local mode needs a single artifact FILE, not a directory`);
@@ -45742,13 +45919,13 @@ async function recordRoundtripProof(ctx, artifactSha256, rows, verdict) {
       return;
     }
     const repoDir = resolveRepoDir(ctx.cwd, { ...env2 !== void 0 ? { env: env2 } : {} });
-    const probe = await probeEngines(effective.config, { ...env2 !== void 0 ? { env: env2 } : {} });
-    if (probe.degraded) {
+    const probe2 = await probeEngines(effective.config, { ...env2 !== void 0 ? { env: env2 } : {} });
+    if (probe2.degraded) {
       notice("engine probe degraded \u2014 cannot mint the rulesHash this proof must match; proof NOT recorded");
       return;
     }
     const rulesHash = await computeCheckRulesHash({
-      engineVersions: probe.engineVersions,
+      engineVersions: probe2.engineVersions,
       configDigest: computeConfigDigest(effective),
       ...env2 !== void 0 ? { env: env2 } : {}
     });
@@ -45773,7 +45950,7 @@ var runRoundtrip = (ctx) => runRoundtripCore(ctx);
 init_define_BORDER_BUILD();
 var import_yaml2 = __toESM(require_dist(), 1);
 import { spawnSync as spawnSync20 } from "node:child_process";
-import { existsSync as existsSync25, mkdirSync as mkdirSync13, readFileSync as readFileSync24, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync10 } from "node:fs";
+import { existsSync as existsSync26, mkdirSync as mkdirSync13, readFileSync as readFileSync24, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync10 } from "node:fs";
 import { dirname as dirname19, join as join39 } from "node:path";
 var realIo = {
   read: (p) => readFileSync24(p, "utf8"),
@@ -45785,7 +45962,7 @@ var realIo = {
   mkdir0700: (p) => {
     let cur = p;
     const stack = [];
-    while (!existsSync25(cur) && cur !== "/" && cur !== ".") {
+    while (!existsSync26(cur) && cur !== "/" && cur !== ".") {
       stack.push(cur);
       cur = dirname19(cur);
     }
@@ -45793,7 +45970,7 @@ var realIo = {
       mkdirSync13(dir, { mode: 448 });
     }
   },
-  exists: (p) => existsSync25(p),
+  exists: (p) => existsSync26(p),
   remove: (p) => unlinkSync2(p),
   remotes: (cwd) => {
     const r = spawnSync20("git", ["-C", cwd, "remote", "-v"], { encoding: "utf8" });
@@ -45973,7 +46150,7 @@ function synthesizeScanConfig(eco) {
 
 // src/scan/materialize.ts
 init_define_BORDER_BUILD();
-import { existsSync as existsSync26, mkdirSync as mkdirSync14, readdirSync as readdirSync13, readFileSync as readFileSync25, rmSync as rmSync17, writeFileSync as writeFileSync11 } from "node:fs";
+import { existsSync as existsSync27, mkdirSync as mkdirSync14, readdirSync as readdirSync13, readFileSync as readFileSync25, rmSync as rmSync17, writeFileSync as writeFileSync11 } from "node:fs";
 import { join as join40 } from "node:path";
 var CRATES_ENVELOPE_FILES = ["Cargo.toml.orig", ".cargo-ok", ".cargo_vcs_info.json"];
 var fail3 = (why) => {
@@ -45996,7 +46173,7 @@ function unwrapSingleDir(dir) {
   return dir;
 }
 function requireManifest(repoDir, ecosystem, candidates) {
-  if (!candidates.some((rel) => existsSync26(join40(repoDir, rel)))) {
+  if (!candidates.some((rel) => existsSync27(join40(repoDir, rel)))) {
     fail3(`${ecosystem} package tree has none of [${candidates.join(", ")}] at its root`);
   }
 }
@@ -46016,7 +46193,7 @@ function materializePackage(o) {
     const outer = repoDir;
     const dataCandidates = findNativeMissArchives(outer).filter((f) => f.endsWith("data.tar.gz"));
     const inner = dataCandidates[0] ?? join40(outer, "data.tar.gz");
-    if (!existsSync26(inner)) fail3(".gem archive contains no data.tar.gz");
+    if (!existsSync27(inner)) fail3(".gem archive contains no data.tar.gz");
     const gemTree = join40(o.baseDir, "gem-tree");
     mkdirSync14(gemTree, { recursive: true });
     extractFlat(inner, gemTree);
@@ -46029,7 +46206,7 @@ function materializePackage(o) {
     requireManifest(repoDir, o.ecosystem, ["Cargo.toml"]);
     for (const file2 of CRATES_ENVELOPE_FILES) {
       const path4 = join40(repoDir, file2);
-      if (!existsSync26(path4)) continue;
+      if (!existsSync27(path4)) continue;
       const original = readFileSync25(path4);
       rmSync17(path4, { force: true });
       note(`border scan: crates envelope normalized: ${file2} sha256=${sha256Hex4(original)}`);
@@ -46142,6 +46319,7 @@ function runStatus(ctx) {
     return EXIT_ERROR;
   }
   for (const w of ledger.warnings) ctx.stderr(`border: WARNING ${w}`);
+  ctx.stdout(`engine: ${engineBuild()}`);
   try {
     const drift = remoteTrackingDrift(repoDir);
     const names = drift.configured.length > 0 ? drift.configured.join(", ") : "(none configured \u2014 nothing can ever be pushed)";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "border-customs",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "//": "publint is a runtime dep (exact pin): the npm-stage engine is invoked via bin resolution against the installed layout, so consumers get the publint-fail leg out of the box; the dev suite resolves the same node_modules/.bin/publint — no devDependencies entry is needed for it to stay green.",
   "description": "Fail-closed git push gate: secret scanning + supply-chain checks before any remote leaves the machine",
   "type": "module",

package/plugin/border.ts

@@ -1,4 +1,4 @@
-// border-opencode-plugin v0.8.3
+// border-opencode-plugin v0.8.5
 // Official opencode plugin adapter for the border fail-closed push gate.
 // Registers ONE agent tool, `border`, that drives the border CLI — argv-only
 // (node:child_process execFile, never a shell), top-level commands restricted
@@ -46,7 +46,7 @@
 // cannot-answer, never a fallback to some other binary.
 
 import { execFile } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
 
@@ -209,25 +209,47 @@ function isBorderHelp(result: CliResult): boolean {
 }
 
 type Resolution =
-  | { readonly ok: true; readonly resolution: BinResolution }
+  | { readonly ok: true; readonly resolution: BinResolution; readonly stamp: string }
   | { readonly ok: false; readonly reasons: readonly string[] };
 
+/** Twin of parseVersionStamp in src/opencode/aspects/globalResolution.ts; the
+ * digit anchor keeps the banner (`border — fail-closed…`) from parsing as a
+ * version. Duplicated on purpose: this file must stay import-free (Route A
+ * drops it as a single standalone file). */
+function parseVersion(stdout: string): string | null {
+  const m = /^border\s+(\d[^\s]*)/m.exec(stdout);
+  return m?.[1] ?? null;
+}
+
+/** The version this plugin module was packaged with (the ./package.json export).
+ * Route A drops (bare file in plugins/) have no sibling package.json: null. */
+function packagedVersion(): string | null {
+  try {
+    const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")) as { version?: unknown };
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Positive handshakes are cached per BORDER_BIN key for the host process's
- * life; failures are never cached, so a mid-session install recovers on the
- * next call. */
-let verified: { readonly key: string; readonly resolution: BinResolution } | null = null;
+ * life (stamp included); failures are never cached, so a mid-session install
+ * recovers on the next call. */
+let verified: { readonly key: string; readonly resolution: BinResolution; readonly stamp: string } | null = null;
 
 async function resolveVerified(): Promise<Resolution> {
   const key = process.env["BORDER_BIN"] ?? "";
   if (verified !== null && verified.key === key) {
-    return { ok: true, resolution: verified.resolution };
+    return { ok: true, resolution: verified.resolution, stamp: verified.stamp };
   }
   const reasons: string[] = [];
   for (const candidate of candidateList()) {
     const probe = await runCli(candidate, ["--help"], PROBE_TIMEOUT_MS);
     if (isBorderHelp(probe)) {
-      verified = { key, resolution: candidate };
-      return { ok: true, resolution: candidate };
+      const version = await runCli(candidate, ["--version"], PROBE_TIMEOUT_MS);
+      const stamp = version.status === 0 ? (parseVersion(version.stdout) ?? "unknown") : "unknown";
+      verified = { key, resolution: candidate, stamp };
+      return { ok: true, resolution: candidate, stamp };
     }
     reasons.push(
       probe.status === 0
@@ -367,11 +389,26 @@ async function buildToolResult(argv: readonly string[]): Promise<string> {
       "--- stderr ---\n(empty)",
     ].join("\n");
   }
+  const shell = `$ border ${argv.join(" ")}`;
+  if ((process.env["BORDER_REQUIRE_PKG_VERSION"] ?? "") === "1") {
+    const own = packagedVersion();
+    const stampCore = resolution.stamp.split("+")[0];
+    if (own === null || own !== stampCore) {
+      return [
+        shell,
+        "exit: 2",
+        `note: cannot-answer — BORDER_REQUIRE_PKG_VERSION=1 demands the resolved CLI report this package's own version (${own ?? "unreadable"}); the resolved face (${resolution.resolution.label}) reported '${resolution.stamp}'. Nothing was run.`,
+        "--- stdout ---\n(empty)",
+        "--- stderr ---\n(empty)",
+      ].join("\n");
+    }
+  }
   const result = await runCli(resolution.resolution, argv, TIMEOUT_MS);
   if (result.spawnFailed) verified = null;
   const sections = [
-    `$ border ${argv.join(" ")}`,
+    shell,
     `exit: ${String(result.status)}`,
+    `face: ${resolution.resolution.label} version=${resolution.stamp}`,
   ];
   if (result.note.length > 0) sections.push(`note: ${result.note}`);
   sections.push(`--- stdout ---\n${result.stdout.length === 0 ? "(empty)" : result.stdout}`);