bzbx: network-diagnostic toolkit

First-party on-device program #12 (ADR-0042).

v1.2 | 2026-07-30

Canonical per ADR-0042. bzbx is the recon complement to CONDUIT (probe-the-network vs. ride-one-host); carts overlay per-protocol decoders + the world’s hosts / services. See the program roster.

Tier 1 — Treatment

Gate: draft (written 2026-07-30, against the ICE Breaker Tier 1 and aethernet.md).

The hook

The deck’s bundled network-diagnostic toolkit: ping / traceroute / nslookup / telnet / wget / nc under one roof, plus a live capture viewer. bzbx answers two questions before the operator commits to anything: what is out there, and what is flowing. Spiritually a busybox for the deck’s net stack, over an authored in-world network.

What the operator does

Scan, read, and choose a door. The operator probes a subnet, watches hosts resolve into a list, reads the ranked capture table for a secret moving in the clear, and traces the route to the next subnet. Findings that matter get committed to DOSSIER; the rest is discarded when the mission ends.

The repeating decision is passive or active: sniff quietly for lower confidence, or probe loudly for higher confidence and more exposure.

Feel

An instrument, never a lever. bzbx reads the world and changes nothing in it, and that constraint is the design rather than a gap. A readout that cannot move the number it displays can be taken at face value. ICE Breaker is the actuator that moves exposure; CONDUIT is the session that leaks it; bzbx is the panel that reports what those two produced.

Three readings follow from read access alone, and together they cover the canon visibility states (aethernet.md):

• Level. The trace meter, labelled with the canon bands rather than a bare integer, so the operator reads invisible, emitting a signature, or hunted.
• Slope. Trace sampled over recent ticks and drawn as a sparkline. Level says where the defenders are; slope says whether the last action was noticed. A flat run under an active probe is the evidence that the probe was quiet.
• Deltas. A host flipping online or revealed marks its row. A defender bringing hosts up during a sweep reads as a cluster of marks, which is a shape instead of a number.

The texture is a workbench under lamplight: dense tables, a filter line, and a readout the operator learns to trust because nothing on this screen can lie about what it cannot touch.

Feasibility verdict

Buildable on what ships. runtime/programs/bzbx/bzbx.lsp already holds the world ingest, the host model, the verb floor, the reveal overlay, capture ranking, the guarded DOSSIER paths, and seven live-world reads. The three readings above need the trace accessor already bound and a sample ring in the program’s own state.

• Reuses: the knEmacs application engine (comint applet output, a tabulated-list capture table, minibuffer completion), the wire house kit, and the World Engine’s network model.
• New surface required: one accent pattern for the delta mark (see Tier 2), and a small filter grammar.

Open questions

• Deferred to the tiers below (see Open / deferred in Tier 3).

Tier 2 — Operator spec

Gate: approved (the v1 design; merged through PR review).

Identity

bzbx is the deck’s bundled network-diagnostic toolkit: ping / traceroute / nslookup / telnet / wget / nc applets under one roof, plus a live capture viewer (a top-style ranked endpoint table, httpinspect lineage). The “read the wire” recon tool: it finds what’s reachable and what’s flowing, and feeds DOSSIER. (Spiritually a busybox for the deck’s net stack.)

• Operator program #12 (ADR-0042). First-party, always-present, bare-launchable, never superseded. The recon complement to CONDUIT (probe-the-network vs. ride-one-host).
• Generic verb floor (ships, bare-launchable): PING/PROBE, TRACEROUTE, RESOLVE (nslookup), FETCH (wget), CONNECT (nc / telnet), CAPTURE-VIEW (a live ranked endpoint table + drill-in detail). Carts overlay per-protocol decoders + the world’s hosts / services.

The surface

Three full-width tabs, selected on PAD-1 / PAD-2 / PAD-3 (decided by Josh, 2026-07-30, over the side-by-side split that shipped in v1). Each tab gets the full content width, which the squeezed two-pane layout denied the capture table.

Tab	Holds	Component
TARGETS	One row per host: state gutter, hostname, address, service, OS guess. Where PROBE, CONNECT, FETCH, and TRACEROUTE act.	data/list
CAPTURE	The ranked endpoint table: endpoint, count, rate, last-seen, latency, secret flag. Sortable, filterable.	data/table
ROUTE	The traceroute result drawn as a network map, with per-hop latency beneath.	network map + data/kv

Above the tabs sits the identity band carrying the scan tag, the counts, and the trace readings from Tier 1. Below sits the filter line and a status echo. The four verb keys are tab-polymorphic, which is what keeps the Row-74 action bar inside its width budget.

One pattern the kit lacks: accent/change-pulse, a single-frame inversion of a row’s leading glyph on the render where that row’s underlying state changed. It belongs in the shared accent set rather than in bzbx, because kn9’s arriving mail and the mission board’s new offers want the same mark. It goes to the workbench and lands as a kit slot before any screen uses it, per the design system.

Bare-launch default world

Per the global bare-launch default-world policy (enrich-never-gate, ADR-0042), bzbx is the one program where the deck looking at itself yields nothing to do: the deck is offline-first and single (no LAN of its own), so a network-recon tool has nothing real to probe bare. Pinging the deck’s own loopback returns nothing of use.

So bare bzbx is honestly empty: the applet menu and an empty capture table are present (the grammar is demonstrable: pick an applet, see its form), and there are no targets and no results until a cart installs a network. It still runs (enrich-never-gate) and sits idle. Contrast Kommander, kn9, Keyring, and RIPSAW, where “the deck itself” is a real and useful surface: a fictional local fs, the operator’s own inbox, keystore, and DOSSIER. bzbx has no such local content, so empty is the honest floor.

What bzbx does NOT own

bzbx reads the wire (recon: many hosts, outside). It does not own:

• The host / the session. Riding one box (the command/response shell, the auth, file pull) is CONDUIT (conduit.md). bzbx finds the door; CONDUIT walks through it.
• File logistics. Moving / staging files is Kommander’s filesystem layer (kommander.md).
• The org / relationship graph. Who connects to whom is RIPSAW (ripsaw.md); bzbx maps wires and streams, and the entity edges belong to RIPSAW.
• The durable record. DOSSIER (dossier.md) is the persistent store; bzbx is a probe: live, this mission, and it emits keys for the record to hold.
• Cracking. Breaking a lock / cipher is Keyring (keyring.md); bzbx may sniff a credential fragment that de-risks Keyring’s crack, but doesn’t crack.
• Visibility. The operator’s exposure is engine-owned and cart-moved (aethernet.md). bzbx displays trace and can never change it: it is the instrument, and ICE Breaker is the actuator. A defender’s awareness state belongs to the cart that owns the contest.
• Missions / economy. Contracts, the objective graph, credits / reputation are mission-layer. Durable consequence is the engine’s via the sanctioned outcome path (ADR-0040).

Tier 3 — Detailed design

Gate: approved (the v1 design; merged through PR review).

Implementation seam (GWP-629): file names, FFI signatures, node schemas, and ADR contracts appear from here down.

The world it reads (:world)

bzbx’s :world is its slice of the central World Engine’s generated world (see ../runtime/world-engine.md): the in-world NETWORK model, the WIRE layer. It is coherent with the rest (a host bzbx finds is the box CONDUIT rides, owned by the entity RIPSAW maps). Materialized lazily on scan; all in-world / simulated (enrichment-contract.md §2). Node types:

Node	Key fields	DOSSIER-discoverable key, or flavor?
host	:addr · :hostname · :reachable? · :os-guess · :revealed? (shared-region reveal flag, the bzbx → CONDUIT invariant)	revealed host = key net:<scan>:host:<addr>
port / service	:port · :proto · :state (open / closed / filtered) · :banner · :service · :version	open port = key host:<addr>:port:<n>; banner / version = key host:<addr>:service:<name>
link / route	:from · :to · :hop-n · :latency (traceroute hops, topology fragments)	topology fragment = key net:<scan>:topology:<frag>
dns-record	:name · :addr · :type (nslookup resolution)	name → addr mapping = key net:<scan>:dns:<name> (a lead)
stream / capture	the live wire as a ranked endpoint table (httpinspect): :endpoint (method + host + path) · :count · :rate · :last-seen · :latency (p50 / p95 / max) · :payload-sample	a plaintext secret / cred / route off the wire = key net:capture:<finding>

Discoverable vs flavor: revealed hosts, open ports, service banners / versions, topology fragments, DNS leads, and tagged capture-findings are keys; closed ports, decorative latency, ambient chatter are flavor. The world region is the single shared mission world-region (run-state): one region per mission (enrichment-contract.md §4). The cart’s world-archetype seeds the network (host count, services, what’s hidden behind what, which streams carry secrets).

Tick-aware: a node coming online or a new stream appearing is a World Engine clock event bzbx shows live (the top table updates). Trace itself is engine-owned and bzbx holds only the six read accessors, so an active scan raises exposure through the mission’s own rules and bzbx reports the result. See aethernet.md.

Scope-line: construction (knEmacs mode vs cell-API)

Verdict: SPLIT, knEmacs mode (primary) + an optional cell-API passenger on the ADR-0046 scope line (ADR-0046). The flagged split:

• Engine side (primary): the applet launcher + the line-tool applets (ping / traceroute / nslookup / wget / nc) are comint output buffers; the capture viewer is a tabulated-list, a top-style sortable, reflowing ranked table (endpoint · count · rate · last-seen · latency) with drill-in detail (per-endpoint p50 / p95 / max, status mix). The httpinspect model is a sortable table plus a detail screen, both pure data and headlessly testable under the engine. The gameplay (find the host, read the banner, spot the secret in the stream) lives in the navigable table.
• cell-API side (optional, deferred): a capture waterfall, “watch the wire scroll,” a real-time animated stream viz. Pure aesthetic, and the verbs act elsewhere. The recommendation is engine-mode primary; waterfall optional, authored on the ui/ cell-API only if a cart wants the texture.

This makes bzbx’s capture table a strong candidate for the shared tabulated-list library the engine extracts next (rule of three: RIPSAW’s attribute table + kn9’s summary buffer are the other two consumers, and the feed-engine insight).

:payload

Small by-value params only, never the network model (that arrives via :world):

(launch-app :bzbx
  :world   relay-7-net                        ; opaque live handle to the network slice
  :payload '(:scan-target "10.0.7.0/24"       ; what to scan (an addr into the world)
             :applet :ping                     ; initial applet
             :mode   :passive))                ; :passive (sniff, lower conf) | :active (probe, higher)

• :scan-target / :applet / :mode: where to look, which tool, how loud. :mode ties to recon depth → DOSSIER :conf (passive ⇒ :rumored / :inferred; active probe / banner-grab ⇒ :verified) and to heat (active is louder, the cart’s wall-clock-heat hook).
• Bare (no :world) ⇒ the honest-empty default world (see Bare-launch default world in Tier 2).

Export to DOSSIER

bzbx emits durable facts only through the sanctioned (dossier-commit <key>) primitive, never a raw write (ADR-0049, ADR-0005). Fact-node fields per dossier-data-model.md §3:

Key	When	Carries
net:<scan>:host:<addr>	a host is revealed by a scan	:conf by mode; sets the shared-region :revealed? flag
host:<addr>:port:<n>	an open port is found	:links (:located-at "<addr>")
host:<addr>:service:<name>	a service banner / version is grabbed	the version (a vuln lead)
net:<scan>:topology:<frag>	traceroute reveals a route / link	:links (:routes-to …): the follow-the-wire edge
net:capture:<finding>	a plaintext secret / cred / route is read off the wire	may carry :routes-to / feed a host:<id>:cred lead → Keyring / CONDUIT

Reads ((dossier-has? <key>)):

• (dossier-has? net:<scan>:host:<addr>) → already-mapped hosts come pre-revealed (de-risk from recon banked in an earlier run).
• bzbx’s reveals are the upstream of the bzbx → CONDUIT chain: a revealed host + committed host:<addr>:reachable is what CONDUIT can target.

Objective-graph ties

Which bzbx verbs fire goal verbs (ADR-0043):

• PROBE/PING reveals a target host → (goal-complete 'locate-<host>), and may (goal-reveal) a downstream ACCESS goal (a found host opens a CONDUIT-access path).
• Banner-grab a service (CONNECT / PROBE) → (goal-complete 'fingerprint-<svc>); a vulnerable version may (goal-reveal) an exploit / Keyring path.
• CAPTURE-VIEW spots a plaintext finding (a sniffed cred / route) → (goal-reveal): e.g. a sniffed credential enables CONDUIT pre-auth (the bzbx → Keyring → CONDUIT chain) or a route reveals the next subnet.
• TRACEROUTE maps topology → (goal-complete 'map-<net>) for OBSERVE / recon goals.
• Observes tick events: a node coming online mid-scan (World Engine clock event) appears live; active scanning under wall-clock heat can advance a defender trace (the mission / knSALK owns that :hold).

Engine reuse

bzbx is a bzbx-mode (with per-applet sub-keymaps) on the knEmacs application engine (built, kec-lisp ADR-0004; see ADR-0046). It consumes:

• comint: applet command / output (shared with REPL / CONDUIT, the line-tools are comint sessions).
• tabulated-list: the top-style ranked capture / endpoint table (sortable columns, reflow, drill-in). This is the piece bzbx most wants and the engine doesn’t yet have as a named library (see Scope-line). bzbx is the first consumer; RIPSAW’s attribute table + kn9’s summary buffer are #2 and #3 → extract a shared tabulated-list lib then, which is also the feed-engine base.
• minibuffer completing-read (command-by-name): pick an applet / target by name.
• define-major-mode: bzbx-mode + applet minor modes.

Optional cell-API passenger: the capture waterfall (see Scope-line), authored on ui/, only if a cart wants it. CIPHER stays OLED-exclusive.

Interfaces

• Launch: (launch-app :bzbx :world <network-handle> :payload '(:scan-target … :applet … :mode …)): NoshAPI Tier 1 (ADR-0049, ADR-0005). :world is the live network slice; :payload is small params only.
• Export: (dossier-commit <key>): sanctioned fact-node deposit; read: (dossier-has? <key> &key min-conf) (ADR-0049, ADR-0005).
• Cell-API note: an optional, deferred capture-waterfall animation is a cell-API passenger on the content rows; the primary capture viewer is an engine tabulated-list.
• Display: draws on the cartridge / content rows (1–73) per the canonical grid (see the Canonical Hardware Specification); grid queried via the cell-API getters.
• Authored in KEC Lisp. Program source lives at runtime/programs/bzbx/ (ADR-0042).

Open / deferred

• The opaque live :world handle. The bzbx → CONDUIT live reveal (a host revealed in the run-region mid-mission, before it’s a DOSSIER fact) needs the opaque live handle. (Update 2026-07-18: the ADR-0049 amendment landed, 2026-06-28; the live handle is built and tested. See worked-mission-walkthrough.md.) The durable-key path (commit :reachable, then CONDUIT gates on it) worked while it was pending.
• The shared tabulated-list library. bzbx is the first consumer of the top-style capture table; the rule-of-three extraction (with RIPSAW + kn9) is engine work; bzbx can ship its own table first (build-then-extract).
• The World Engine spec. The generator + clock + typed-event bus the tick-awareness above depends on is specified in ../runtime/world-engine.md.
• Optional cell-API capture waterfall. The animated stream viz is a deferred texture; the table is the primary surface.
• Recon heat / exposure. Ownership is settled: the engine holds region trace, a cart moves it through play, and every program reports it (aethernet.md). :mode (passive / active) still ties to how much exposure a scan earns, and those numbers stay mission-layer tuning.

Migration notes

• 2026-07-18 tier migration: content re-cut under tier headings from the v1 design; no mechanics changed. World schema, scope-line split, and FFI moved behind the Tier 3 seam; identity and bare-launch behavior stayed at Tier 2. The “forthcoming ADR-0049 amendment” note was stale (the amendment landed 2026-06-28); annotated in place.

References

• enrichment-contract.md: lens / world / shared-region / dossier-commit contract (§1–§6).
• dossier-data-model.md: the fact-node schema a scan finding commits as (§3).
• dossier.md: the durable intel store bzbx emits into.
• conduit.md: the session program that rides the hosts bzbx reveals (the bzbx → CONDUIT chain).
• keyring.md · ripsaw.md · kommander.md: the crack, org-graph, and filesystem layers of the recon cluster.
• ../runtime/world-engine.md: the central World Engine (generator + World Clock + typed-event bus) bzbx’s :world slice reads.
• ../gameplay-framework.md: the gameplay framework the World Engine serves as world model for.
• ADR-0042: first-party programs; carts enrich, never gate.
• ADR-0046: the knEmacs application engine (major modes + minibuffer command-by-name).
• ADR-0049 · ADR-0005: the NoshAPI FFI surface (launch-app / dossier-commit / dossier-has?).
• ADR-0043: the mission objective model bzbx’s verbs fire.
• ADR-0040: the UDS sanctioned-write boundary dossier-commit respects.

Inspirations

Assigned by Josh in the kn86-inspo workbench. Full map: cart-inspiration-map.md. A row marked (cross-listed) was placed on another destination first and serves this one too (2026-07-29 workflow sweep).

Source	Category
mcfly	file browser
NetWatch	dashboard (cross-listed)
octoscope	dashboard (cross-listed)
loglens-core	terminal library (cross-listed)