feat(server): sidecar handshake contract for headless hosts

[paddymul]

Summary

Adds the small server-side surface that a parent supervisor (Tauri desktop app, Electron, raw subprocess driver) needs to spawn python -m buckaroo.server without polling for readiness, inventing session IDs, or hard-coding ports.

All changes are additive and backward-compatible. The existing python -m buckaroo.server --port=8700 --no-browser invocations are unchanged. The MCP tool, standalone browser-tab flow, and Jupyter widget paths all keep working.

Diff: 6 files, +67 / -9.

What changed

• --port=0 random binding. tornado.netutil.bind_sockets recovers the OS-assigned port (Application.listen doesn't expose the bound port). On listen, prints BUCKAROO_PORT=<n> to stdout (line-buffered) before any other output — a deterministic readiness signal for parent processes.
• --stdio-control flag. Server exits when stdin closes. Lets a parent guarantee the sidecar dies when the parent does, more reliable than process-tree teardown across platforms.
• protocol_version: 1 field on initial_state WS messages. Clients can warn on mismatch when the wire format changes incompatibly.
• LoadHandler mints a UUID session server-side when the caller omits it; previously errored. Hosts that already pass a session ID keep working unchanged.
• New buckaroo-server console script entry point (pyproject.toml). Existing buckaroo-table MCP script unchanged. Makes which buckaroo-server discoverable from PATH so a parent can derive the right Python interpreter.
• must be running inside ipython warning routes to stderr. Previously polluted stdout, fine for interactive Jupyter use but breaks any pipe-captured handshake.
• mcp_tool.ensure_server passes --port=<SERVER_PORT> explicitly. Decouples the MCP tool from the argparse default.

Why ship this from buckaroo (vs. a downstream package)

The contract is small and inseparable from the WS protocol it depends on. Downstream desktop integrations (Tauri plugin, Electron wrapper, etc.) consume this contract over __main__'s stdout + the existing WS protocol, but the contract itself ships with buckaroo so it's versioned in lockstep with the WS messages.

Test plan

• pytest tests/unit/ passes (963 passed, 6 skipped, 1 deselected for an unrelated pre-existing flake — test_uvx_no_stdout_pollution has a bug where it closes proc.stdin then calls proc.communicate() causing flush of closed file)
• paddy-format (project's pre-commit hook) clean on all changed files
• --no-browser still works (existing flag, unchanged)
• MCP tool's view_data still passes (verified via test_view_data_call)
• BUCKAROO_PORT=<n> line appears on stdout before any other output, even when the ipython warning would otherwise leak first
• --port=0 binds a random port and the handshake reports the actual bound port (verified end-to-end against a Tauri host that parses the line and opens an internal WS to it)

Follow-ups (separate work)

• Tests for the new behavior (handshake line, --stdio-control, server-mint session, protocol_version).
• A new tests/unit/server/test_sidecar_contract.py smoke test that spawns a subprocess and asserts the contract: port handshake, line-buffering, sessionId minting.
• The downstream Tauri plugin + JS adapter (buckaroo-tauri Rust crate, buckaroo-tauri-adapter npm package, example app) — these will land in a separate repo or follow-up PR. Plan + decision log lives in a worktree at .claude/worktrees/tauri-embedding-plan/TAURI_EMBEDDING_PLAN.md.

🤖 Generated with Claude Code

[github-actions]

📦 TestPyPI package published

pip install --index-strategy unsafe-best-match --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ buckaroo==0.13.5.dev25737317319

or with uv:

uv pip install --index-strategy unsafe-best-match --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ buckaroo==0.13.5.dev25737317319

MCP server for Claude Code

claude mcp add buckaroo-table -- uvx --from "buckaroo[mcp]==0.13.5.dev25737317319" --index-strategy unsafe-best-match --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ buckaroo-table

📖 Docs preview

🎨 Storybook preview

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 78184cb8f7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Apply the port fix to the packaged MCP entry point

The BUCKAROO_PORT fix is applied to buckaroo/mcp_tool.py, but the installed buckaroo-table console script still points at the top-level buckaroo_mcp_tool:main in pyproject.toml, and that file still starts python -m buckaroo.server without --port. In packaged/uvx MCP usage with BUCKAROO_PORT set to anything other than 8700, the tool will continue polling the requested port while the spawned server binds to the default port, so the startup failure this change is meant to address remains on the actual entry point.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Propagate the OS-assigned port into app settings

When the new --port 0 path is used and a /load request does not set no_browser, the server binds a real bound_port here but the application was created with make_app(port=args.port), so LoadHandler._handle_browser_window() still reads port=0 from settings and opens/focuses http://localhost:0/s/... instead of the actual listener. This breaks the browser-launch flow for random-port servers even though the stdout handshake reports the correct port.

Useful? React with 👍 / 👎.