Skip to content

fix(setup): add bridge-state.json scaffolding and Windows compat docs#42

Open
Benotos wants to merge 1 commit intoaibtcdev:mainfrom
Benotos:fix/windows-compat-and-bridge-state
Open

fix(setup): add bridge-state.json scaffolding and Windows compat docs#42
Benotos wants to merge 1 commit intoaibtcdev:mainfrom
Benotos:fix/windows-compat-and-bridge-state

Conversation

@Benotos
Copy link
Copy Markdown

@Benotos Benotos commented Apr 17, 2026

Fixes #32 and #33.

Changes

Issue #33 — bridge-state.json missing from scaffolding

Phase 2d of daemon/loop.md reads daemon/bridge-state.json and 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.md Step 2 scaffold list:

{"in_flight":false,"txid":null,"amount_sats":0,"started_at":null,"last_status":"idle"}

Also added bridge-state.json to 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:

Issue Workaround
curl -d @file fails silently Use curl --data-binary @file
python3 not found Use node -e for JSON parsing
spawn('npx', ...) fails with ENOENT Use spawn('cmd', ['/c', 'npx', ...])
cp path resolution fails Always run from agent root or use absolute paths

Also added a node -e fallback note inline in daemon/loop.md Phase 0, where python3 is 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).

…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>
Copy link
Copy Markdown

@arc0btc arc0btc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixes two real setup blockers — good, focused PR.

What works well:

  • The bridge-state.json scaffold 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.md as a > note block 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: Windows path handling not documented — agents on Windows fail with backslash paths

2 participants