feat(transport): cross-platform IPC — rebased #180 on current main

[midirectiekade14-debug]

Summary

Rebases @MICORT's PR #180 (feat(transport): cross-platform IPC with TCP loopback on Windows) onto current main, with one merge conflict resolved, and verifies all transport tests pass on Windows 11 + Python 3.14.

Credit belongs to @MICORT — the transport module, tests, and Windows bootstrap logic are entirely their work. This PR exists only because #180 went mergeable: false after main moved on, and it's useful to have a ready-to-merge version. Maintainers: happy to close this in favor of #180 being refreshed by the original author.

What changed vs. #180

One conflict in helpers.py:

• main renamed screenshot() → capture_screenshot() (breaking API — used by 20+ domain-skills files)
• feat(transport): cross-platform IPC with TCP loopback on Windows #180's version introduced a platform-aware default path via transport.state_dir()

Resolution keeps the capture_screenshot name (main's API) and the platform-aware default (#180's fix):

def capture_screenshot(path=None, full=False):
    if path is None:
        path = str(transport.state_dir() / "shot.png")
    ...

SKILL.md conflict was resolved by taking main's version (the doc reorganization that happened after #180 was opened).

Verification

On Windows 11 Pro, Python 3.14.3:

$ uv run python -m pytest tests/
======================== 24 passed, 1 skipped in 1.09s ========================

End-to-end smoke test against local Chrome (remote-debugging on port 9222):

new_tab('https://example.com')
wait_for_load()
capture_screenshot(path='C:/tmp/bh.png')
page_info()
# → {'url': 'https://example.com/', 'title': '🟢 Example Domain', 'w': 929, 'h': 917, ...}

browser-harness --doctor reports transport tcp 127.0.0.1:<port> correctly; previously it traceback'd on socket.AF_UNIX missing.

Windows install notes (not code changes — just observations for maintainers)

Two things I had to work around locally but that aren't in-scope for this PR:

1. Python 3.14 on Windows prints 🟢 with cp1252 by default → print(page_info()) crashes with UnicodeEncodeError. Workaround: PYTHONIOENCODING=utf-8. Could be fixed in run.py with sys.stdout.reconfigure(encoding='utf-8').
2. The daemon subprocess (uv run daemon.py) needs uv on PATH. On Windows that path (%APPDATA%\Python\Python3xx\Scripts\) isn't always on the default user PATH.

Happy to submit these as a follow-up PR if useful.

---

Summary by cubic

Introduces a cross-platform IPC transport: UDS on macOS/Linux and loopback TCP on Windows. Centralizes paths, server/client creation, and process spawn logic in transport.py, fixing Windows startup and improving diagnostics.

• New Features

  • New transport.py exposes endpoint discovery and IPC: descriptor JSON {v:1, kind, host|path, port} with atomic writes and cleanup.
  • Windows binds 127.0.0.1:<ephemeral>; POSIX uses UDS with 0600 perms.
  • --doctor now shows transport and endpoint for the current BU_NAME.
  • capture_screenshot() uses transport.state_dir() when no path is given.

• Bug Fixes

  • Daemon/log/pid/version-cache paths use %TEMP% on Windows (no /tmp dependency).
  • Detached spawn uses Windows DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP; POSIX keeps start_new_session=True.
  • On start/restart, stale endpoint/socket files are removed to avoid bind failures.
  • admin.ensure_daemon/restart_daemon and daemon use transport for probing, endpoint writes, and cleanup.

^{Written for commit 2accac4. Summary will update on new commits.}

[browser-harness-review]

✅ Skill review passed

Reviewed 1 file(s) — no findings.

[cubic-dev-ai]

1 issue found across 8 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="transport.py">

<violation number="1" location="transport.py:171">
P1: `is_alive()` catches a narrow exception tuple that does not cover all errors from malformed endpoint descriptors, violating its documented contract that malformed descriptors return `False`. `open_client_sync()` can raise `KeyError`, `TypeError`, or `AttributeError` for bad JSON shapes, missing keys, or platform-incompatible kinds, none of which are caught.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

P1: is_alive() catches a narrow exception tuple that does not cover all errors from malformed endpoint descriptors, violating its documented contract that malformed descriptors return False. open_client_sync() can raise KeyError, TypeError, or AttributeError for bad JSON shapes, missing keys, or platform-incompatible kinds, none of which are caught.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At transport.py, line 171:

<comment>`is_alive()` catches a narrow exception tuple that does not cover all errors from malformed endpoint descriptors, violating its documented contract that malformed descriptors return `False`. `open_client_sync()` can raise `KeyError`, `TypeError`, or `AttributeError` for bad JSON shapes, missing keys, or platform-incompatible kinds, none of which are caught.</comment>

<file context>
@@ -0,0 +1,174 @@
+    """
+    try:
+        s = open_client_sync(name, timeout=timeout)
+    except (FileNotFoundError, ConnectionRefusedError, socket.timeout, OSError, ValueError):
+        return False
+    s.close()
</file context>

Suggested change

	except (FileNotFoundError, ConnectionRefusedError, socket.timeout, OSError, ValueError):
	except (FileNotFoundError, ConnectionRefusedError, socket.timeout, OSError, ValueError, KeyError, TypeError, AttributeError):

[qodo-ai-reviewer]

Hi, daemon.serve() assumes transport.read_endpoint() returns a dict and calls desc.get()/indexes keys; if the endpoint file is missing or malformed it returns None and the daemon crashes during startup logging. This can turn a recoverable endpoint-file issue into a fatal daemon startup failure.

Severity: action required | Category: reliability

How to fix: Guard/validate endpoint descriptor

Agent prompt to fix - you can give this to your LLM of choice:

Issue description

daemon.py reads the endpoint descriptor back from disk after start_ipc_server() and assumes it is a dict with required keys. transport.read_endpoint() can return None (missing file, malformed JSON), and even when it returns a dict it may be missing keys, causing daemon startup to crash.

Issue Context

This crash happens in the startup path, right after starting the IPC server. Even if the server is actually running, the daemon can exit due to the logging line.

Fix Focus Areas

• daemon.py[217-221]
  • Handle desc is None defensively (e.g., log a fallback like "listening (endpoint unreadable)"), or avoid re-reading from disk and instead have start_ipc_server() return the descriptor alongside the server.
  • Avoid direct indexing (desc['host']) without checking key presence.
• transport.py[113-135]
  • (Optional) return (server, descriptor) or provide a helper that returns the descriptor used for writing.

We noticed a couple of other issues in this PR as well - happy to share if helpful.

---

Found by Qodo. Free code review for open-source maintainers.