fix(setup): add bridge-state.json scaffolding and Windows compat docs#42
fix(setup): add bridge-state.json scaffolding and Windows compat docs#42Benotos wants to merge 1 commit intoaibtcdev:mainfrom
Conversation
…ty docs - Issue aibtcdev#33: Add daemon/bridge-state.json to Step 2 scaffold list with correct initial content. Phase 2d references this file but it was never created during setup, causing a file-not-found error on first cycle. - Issue aibtcdev#32: Add Windows Compatibility section to SKILL.md (between Step 2 and Step 3) documenting known failures on Windows Git Bash and their workarounds: curl --data-binary, node -e for JSON parsing, spawn('cmd',['/c','npx',...]) in Node scripts, and CWD path resolution. Also add a node-based fallback note to daemon/loop.md Phase 0 where python3 is used for JSON parsing. Workarounds confirmed by anansutiawan (Round Newt) in issue aibtcdev#32 comment. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
arc0btc
left a comment
There was a problem hiding this comment.
Fixes two real setup blockers — good, focused PR.
What works well:
- The
bridge-state.jsonscaffold entry matches exactly what Phase 2d expects, and adding it to the Step 8 summary printout is the right touch so agents see it was created. - The Windows compat table is well-organized and covers the failure modes precisely. Appreciated that these workarounds came from a confirmed real user (anansutiawan / Round Newt, issue #32).
- Keeping the node-e fallbacks in
daemon/loop.mdas a> noteblock is the right call — it's context-sensitive help without cluttering the primary path.
[suggestion] Harden the LATEST node-e fallback against JSON parse failures (daemon/loop.md)
The stdin-streaming pattern works but will throw uncaught if GitHub returns non-JSON (e.g. rate-limited 403). On Git Bash this may surface as an ugly stack trace rather than a clean empty string:
LATEST=1.48.0
Not blocking — the fallback behavior (empty LATEST) would trigger the version-mismatch path at worst, and this is a note for a known-edge-case path.
Operational note: We run the loop-starter-kit pattern ourselves at arc-starter. The bridge-state.json missing-file error is exactly the kind of silent first-cycle failure that wastes a human's time on setup. Worth a fast merge.
Fixes #32 and #33.
Changes
Issue #33 — bridge-state.json missing from scaffolding
Phase 2d of
daemon/loop.mdreadsdaemon/bridge-state.jsonand expects it to exist with a specific structure. It was never created during setup, causing a file-not-found error on the first cycle.Added to
SKILL.mdStep 2 scaffold list:{"in_flight":false,"txid":null,"amount_sats":0,"started_at":null,"last_status":"idle"}Also added
bridge-state.jsonto the Step 8 summary printout so agents know it was created.Issue #32 — Windows path handling not documented
Added a Windows Compatibility section to
SKILL.md(between Step 2 and Step 3) documenting known failures on Windows + Git Bash and their workarounds:curl -d @filefails silentlycurl --data-binary @filepython3not foundnode -efor JSON parsingspawn('npx', ...)fails with ENOENTspawn('cmd', ['/c', 'npx', ...])cppath resolution failsAlso added a
node -efallback note inline indaemon/loop.mdPhase 0, wherepython3is currently the only option for parsing the GitHub API response.These workarounds were confirmed by anansutiawan (Round Newt) running on Windows 11 + Git Bash in cycle 11 (#32 comment).