forge: step 1 — bootstrap wrapper workflow

.forge/research/codex-analysis.md

@@ -0,0 +1,214 @@
+warning: `--full-auto` is deprecated; use `--sandbox workspace-write` instead.
+OpenAI Codex v0.130.0
+--------
+session id: 019e2739-3393-7972-a90b-79f1a369eb12
+--------
+user
+Read .forge/PROJECT.md. Then write a concise research analysis to stdout. Do NOT review any code or plan. Do NOT search the web — analyze based on your training knowledge.
+
+Cover these sections with specific, opinionated recommendations:
+1. EXISTING SOLUTIONS — what open-source and commercial products exist in this space
+2. RECOMMENDED STACK — specific libraries with versions, and what to avoid
+3. ARCHITECTURE — how to structure the system, component boundaries, data flow
+4. PITFALLS — domain-specific mistakes and how to prevent them
+5. QUESTIONS — what you would ask before building this
+
+Output ONLY your analysis text. No tool call logs, no search results, just the analysis.
+2026-05-14T16:02:02.319622Z ERROR rmcp::transport::worker: worker quit with fatal: Transport channel closed, when Auth(TokenRefreshFailed("Server returned error response: invalid_grant: Token refresh failed: invalid or expired grant"))
+ succeeded in 0ms:
+# Forge Project
+
+## Description
+Build firmware for MeshCore bots using the standard MeshCore bot project (https://github.com/agessaman/meshcore-bot.git) and MeshCore companion firmware (https://github.com/meshcore-dev/MeshCore.git). The goal is to reduce bot adverts and evaluate/build a built-in response coordinator in firmware as a better alternative to the current VPS coordinator.
+
+## Constraints
+- Use the upstream MeshCore bot project and MeshCore companion firmware as primary references.
+- Target all MeshCore companion device types where feasible.
+- Perform only read-only discovery on local GitHub projects and the hosts `cj-vps` and `cjvana@10.0.0.222` unless later authorized otherwise.
+- Deliverable type: code.
+
+## Context
+- Greenfield/Brownfield: New project in the Colorado Mesh org, starting from an empty local directory.
+- Platform: MeshCore companion firmware / embedded firmware for companion device types.
+- Deliverable type: code
+- Date: 2026-05-14
+
+## Initial Questions and Answers
+- What kind of deliverable should Forge produce? Code project.
+- New project or existing local project? New project in the Colorado Mesh org.
+- Which target hardware should the first firmware build support? All companion types.
+- May local projects and named hosts be inspected? Read-only discovery is OK.
+
+## Candidate Coordination Approach
+The user suggested using configured transmit and receive delays to bias which bot responds, potentially approximating which bot is closest or most appropriate for the original message. Proposed topology tiers:
+
+- HILLTOP: highest elevation / backbone infrastructure, typical neighbors 20+, commands `set txdelay 2`, `set direct.txdelay 2`, `set rxdelay 3`.
+- FOOTHILLS: mid elevation bridge nodes, typical neighbors 10-20, commands `set txdelay 1.5`, `set direct.txdelay 1`, `set rxdelay 3`.
+- SUBURBAN: average rooftop installs, typical neighbors 5-10, commands `set txdelay 0.8`, `set direct.txdelay 0.4`, `set rxdelay 3`.
+- LOCAL: low elevation / immediate area, typical neighbors 1-3, commands `set txdelay 0.3`, `set direct.txdelay 0.1`, `set rxdelay 3`.
+- MOBILE: variable elevation, should defer to fixed infrastructure, commands `set txdelay 3`, `set direct.txdelay 2.5`, `set rxdelay 3`.
+
+Research and planning should evaluate whether this delay-tier model can reduce duplicate bot adverts/responses, whether it conflicts with MeshCore's existing TX/RX timing semantics, and whether extra coordinator messages are still needed.
+
+codex
+1. EXISTING SOLUTIONS
+
+Open source: MeshCore is the correct substrate; stay close to its companion firmware and bot project instead of inventing a parallel mesh layer. Meshtastic is the closest comparable mature LoRa mesh ecosystem and is useful for lessons on channel utilization, node roles, store-and-forward behavior, and UX, but its chat-first model should not be copied wholesale. Reticulum/LXMF is relevant for delay-tolerant addressing and opportunistic links. APRS/LoRa APRS is worth studying for beacon discipline, duplicate suppression, and digipeater etiquette. ChirpStack/LoRaWAN stacks solve a different centralized network-server problem and are mostly a cautionary example here.
+
+Commercial: goTenna Pro, Garmin inReach, ZOLEO, Somewear, Rajant, Silvus, StreamCaster, and Doodle Labs all solve parts of resilient off-grid messaging or tactical mesh. The useful takeaway is not their architecture, which is mostly closed and heavier than MeshCore, but their policy model: role-aware nodes, conservative airtime use, explicit priority, and aggressive duplicate suppression.
+
+Opinionated recommendation: build a distributed soft-coordination layer inside the bot firmware, not a firmware clone of the VPS coordinator. Delay-based response suppression is the right first mechanism because every explicit coordinator frame costs scarce airtime.
+
+2. RECOMMENDED STACK
+
+Use the upstream MeshCore build system and dependency pins wherever they already exist. Do not introduce a new RTOS, packet stack, or language runtime.
+
+Recommended additions if the project needs new code:
+- C++17, matching upstream embedded style.
+- PlatformIO Core 6.1.x for reproducible multi-board firmware builds if upstream already uses PlatformIO.
+- RadioLib 7.1.x only if MeshCore already depends on it or exposes it cleanly; otherwise use MeshCore radio abstractions directly.
+- nanopb 0.4.9.1 only for compact structured payloads that must evolve over time.
+- ArduinoJson 7.2.x only for local config import/export or serial diagnostics, not over the air.
+- Unity 2.6.x for embedded unit tests.
+- Python 3.12, pytest 8.3.x, Hypothesis 6.112.x, and SimPy 4.1.x for host-side coordination and airtime simulations.
+
+Avoid: JSON over LoRa, MQTT in firmware, full protobuf runtimes, SQLite, dynamic plugin systems, heap-heavy callback code, custom radio drivers, and any design that requires every bot to hear every other bot.
+
+3. ARCHITECTURE
+
+Structure the firmware as a bot coordination module sitting above MeshCore transport:
+
+RX path: MeshCore packet -> bot request classifier -> request ID normalization -> eligibility engine -> response scheduler.
+
+TX path: pending response intent -> suppression window -> overheard-response cancellation -> final response publish -> seen/sent ring buffer update.
+
+Core components:
+- Request classifier: identifies bot-triggering messages and derives a stable idempotency key from origin, command type, normalized content, and a short time bucket.
+- Eligibility engine: decides whether this bot may answer based on role, capability, directness, recent neighbor observations, and command type.
+- Scheduler: computes `response_at = rx_time + role_delay + airtime_scaled_jitter`.
+- Suppression cache: cancels pending responses when an equivalent valid response is heard.
+- Metrics: counts eligible, deferred, canceled, transmitted, duplicate-heard, and hidden-node-suspected events.
+- Config: expose role, base delay, jitter, suppression window, and command-specific overrides through the existing MeshCore CLI/config style.
+
+The proposed tier model is directionally good: LOCAL and SUBURBAN should usually answer before HILLTOP and MOBILE. Treat the tiers as policy priority, not true distance. Do not overload MeshCore's core `txdelay` semantics if those affect all radio traffic; add bot-specific coordination delays instead. The suppression window should be longer than the slowest role delay plus worst-case packet airtime plus jitter. A universal `rxdelay 3` is likely too short if MOBILE can delay 3 seconds.
+
+Do not add coordinator claim frames in the first version. Measure duplicate rate first. If duplicates remain unacceptable, add a very small authenticated "claim" frame only for expensive or high-noise responses.
+
+4. PITFALLS
+
+Delay tiers will not solve hidden nodes. Two bots may both hear the requester but not each other. Prevent damage with idempotency keys, client-side duplicate tolerance, and metrics that reveal hidden-node cases.
+
+Neighbor count is not proximity. Hilltop nodes may hear many nodes but be the wrong responder for local context. Use configured role first, observed directness second, RSSI/SNR only as a weak tie-breaker.
+
+Airtime math matters. LoRa packet airtime can dominate small delay differences, especially at slow spreading factors. Jitter should scale with estimated airtime, not be a fixed tiny random number.
+
+Do not run logic inside radio callbacks. Callbacks should enqueue compact events; normal firmware loop/task code should parse, schedule, and transmit.
+
+Do not persist every seen request. Use RAM ring buffers for hot dedupe and write config/metrics sparingly to avoid flash wear.
+
+Do not trust unauthenticated suppression. A forged response or claim could silence all bots. Reuse MeshCore identity/authentication primitives where available.
+
+Do not assume all companion device types have equal RAM, flash, display, BLE, or radio behavior. Keep the coordinator core platform-neutral and put board-specific behavior behind existing MeshCore abstractions.
+
+5. QUESTIONS
+
+What exact traffic should be suppressed: bot adverts, command replies, telemetry, direct-message responses, or all of them?
+
+What duplicate rate and response latency are acceptable in the field?
+
+Should the system prefer the nearest/local bot, the most reliable fixed bot, or the least airtime-costly bot?
+
+How does the current VPS coordinator decide winners, and what failures are driving the firmware replacement?
+
+Are role tiers manually configured, automatically inferred, or both?
+
+Which companion device is the minimum hardware baseline for RAM, flash, and radio capability?
+
+Can packet formats change, or must this remain fully compatible with stock MeshCore nodes?
+
+Are adversarial or misconfigured nodes in scope for the security model?
+
+What RF settings, region, channel usage, and typical packet sizes should simulations target?
+
+Should emergency/admin commands bypass normal delay suppression?
+22,375
+1. EXISTING SOLUTIONS
+
+Open source: MeshCore is the correct substrate; stay close to its companion firmware and bot project instead of inventing a parallel mesh layer. Meshtastic is the closest comparable mature LoRa mesh ecosystem and is useful for lessons on channel utilization, node roles, store-and-forward behavior, and UX, but its chat-first model should not be copied wholesale. Reticulum/LXMF is relevant for delay-tolerant addressing and opportunistic links. APRS/LoRa APRS is worth studying for beacon discipline, duplicate suppression, and digipeater etiquette. ChirpStack/LoRaWAN stacks solve a different centralized network-server problem and are mostly a cautionary example here.
+
+Commercial: goTenna Pro, Garmin inReach, ZOLEO, Somewear, Rajant, Silvus, StreamCaster, and Doodle Labs all solve parts of resilient off-grid messaging or tactical mesh. The useful takeaway is not their architecture, which is mostly closed and heavier than MeshCore, but their policy model: role-aware nodes, conservative airtime use, explicit priority, and aggressive duplicate suppression.
+
+Opinionated recommendation: build a distributed soft-coordination layer inside the bot firmware, not a firmware clone of the VPS coordinator. Delay-based response suppression is the right first mechanism because every explicit coordinator frame costs scarce airtime.
+
+2. RECOMMENDED STACK
+
+Use the upstream MeshCore build system and dependency pins wherever they already exist. Do not introduce a new RTOS, packet stack, or language runtime.
+
+Recommended additions if the project needs new code:
+- C++17, matching upstream embedded style.
+- PlatformIO Core 6.1.x for reproducible multi-board firmware builds if upstream already uses PlatformIO.
+- RadioLib 7.1.x only if MeshCore already depends on it or exposes it cleanly; otherwise use MeshCore radio abstractions directly.
+- nanopb 0.4.9.1 only for compact structured payloads that must evolve over time.
+- ArduinoJson 7.2.x only for local config import/export or serial diagnostics, not over the air.
+- Unity 2.6.x for embedded unit tests.
+- Python 3.12, pytest 8.3.x, Hypothesis 6.112.x, and SimPy 4.1.x for host-side coordination and airtime simulations.
+
+Avoid: JSON over LoRa, MQTT in firmware, full protobuf runtimes, SQLite, dynamic plugin systems, heap-heavy callback code, custom radio drivers, and any design that requires every bot to hear every other bot.
+
+3. ARCHITECTURE
+
+Structure the firmware as a bot coordination module sitting above MeshCore transport:
+
+RX path: MeshCore packet -> bot request classifier -> request ID normalization -> eligibility engine -> response scheduler.
+
+TX path: pending response intent -> suppression window -> overheard-response cancellation -> final response publish -> seen/sent ring buffer update.
+
+Core components:
+- Request classifier: identifies bot-triggering messages and derives a stable idempotency key from origin, command type, normalized content, and a short time bucket.
+- Eligibility engine: decides whether this bot may answer based on role, capability, directness, recent neighbor observations, and command type.
+- Scheduler: computes `response_at = rx_time + role_delay + airtime_scaled_jitter`.
+- Suppression cache: cancels pending responses when an equivalent valid response is heard.
+- Metrics: counts eligible, deferred, canceled, transmitted, duplicate-heard, and hidden-node-suspected events.
+- Config: expose role, base delay, jitter, suppression window, and command-specific overrides through the existing MeshCore CLI/config style.
+
+The proposed tier model is directionally good: LOCAL and SUBURBAN should usually answer before HILLTOP and MOBILE. Treat the tiers as policy priority, not true distance. Do not overload MeshCore's core `txdelay` semantics if those affect all radio traffic; add bot-specific coordination delays instead. The suppression window should be longer than the slowest role delay plus worst-case packet airtime plus jitter. A universal `rxdelay 3` is likely too short if MOBILE can delay 3 seconds.
+
+Do not add coordinator claim frames in the first version. Measure duplicate rate first. If duplicates remain unacceptable, add a very small authenticated "claim" frame only for expensive or high-noise responses.
+
+4. PITFALLS
+
+Delay tiers will not solve hidden nodes. Two bots may both hear the requester but not each other. Prevent damage with idempotency keys, client-side duplicate tolerance, and metrics that reveal hidden-node cases.
+
+Neighbor count is not proximity. Hilltop nodes may hear many nodes but be the wrong responder for local context. Use configured role first, observed directness second, RSSI/SNR only as a weak tie-breaker.
+
+Airtime math matters. LoRa packet airtime can dominate small delay differences, especially at slow spreading factors. Jitter should scale with estimated airtime, not be a fixed tiny random number.
+
+Do not run logic inside radio callbacks. Callbacks should enqueue compact events; normal firmware loop/task code should parse, schedule, and transmit.
+
+Do not persist every seen request. Use RAM ring buffers for hot dedupe and write config/metrics sparingly to avoid flash wear.
+
+Do not trust unauthenticated suppression. A forged response or claim could silence all bots. Reuse MeshCore identity/authentication primitives where available.
+
+Do not assume all companion device types have equal RAM, flash, display, BLE, or radio behavior. Keep the coordinator core platform-neutral and put board-specific behavior behind existing MeshCore abstractions.
+
+5. QUESTIONS
+
+What exact traffic should be suppressed: bot adverts, command replies, telemetry, direct-message responses, or all of them?
+
+What duplicate rate and response latency are acceptable in the field?
+
+Should the system prefer the nearest/local bot, the most reliable fixed bot, or the least airtime-costly bot?
+
+How does the current VPS coordinator decide winners, and what failures are driving the firmware replacement?
+
+Are role tiers manually configured, automatically inferred, or both?
+
+Which companion device is the minimum hardware baseline for RAM, flash, and radio capability?
+
+Can packet formats change, or must this remain fully compatible with stock MeshCore nodes?
+
+Are adversarial or misconfigured nodes in scope for the security model?
+
+What RF settings, region, channel usage, and typical packet sizes should simulations target?
+
+Should emergency/admin commands bypass normal delay suppression?