Dual Side Debug

dual-side-debug

Inspect logs from the macOS host and the Windows peer in a single, time-aligned view.

This project is a Go/Wails desktop app where two peers (macOS + Windows) sync clipboard / files over an iroh-based network. The Windows machine's AppData/Local is exposed to the Mac via SMB and mounted at /tmp/win-local/, so both sides' JSONL logs are reachable from this host.

The helper script lives at .agents/skills/dual-side-debug/dual-logs.sh. It is the only thing you should need to invoke for log work — do not hand-roll ls/tail/jq pipelines unless the script can't express what you need.

Log layout you must remember

• macOS logs: ~/Library/Logs/app.uniclipboard.desktop[-<UC_PROFILE>]/uniclipboard-{gui,daemon,cli}.json.YYYY-MM-DD — Apple convention (~/Library/Logs/<app>); the profile dir is the log dir, there is no logs/ subdir on macOS.
• Windows logs (mounted): /tmp/win-local/app.uniclipboard.desktop[-<WIN_PROFILE>]/logs/uniclipboard-{gui,daemon,cli}.json.YYYY-MM-DD — Windows keeps the logs/ subdir under the data-local app root.
• Per-role files (since the platform-log-dir split): each process writes its own family — gui (Go/Wails host), daemon (uniclipd), cli (uniclip) — daily rotation, 7-day retention. dual-logs.sh picks the newest by mtime per side, i.e. the busiest process (usually the daemon for sync/pairing/transfer). The legacy single-file name uniclipboard.json.YYYY-MM-DD is still matched for old logs. For per-role single-host digging, use the local-log-debug skill instead.
• Format: JSON Lines. Each line has at least timestamp (UTC, ISO-8601 with Z, always the first field), level, target, message, span, device_id, plus structured fields.
• The date in the filename is UTC, not local time. A file named ...2026-04-25 can be the live file while it is still 2026-04-24 in PDT.

Mount setup (do this once per Mac reboot)

The Windows logs only exist on this Mac because an SMB share is mounted from DESKTOP-HIC7MLI. The mount point is not auto-created — you must mkdir it first (otherwise mount_smbfs fails with No such file or directory), and the mount itself does not survive a reboot or a disconnect.

Before debugging, verify a mount exists:

mount | grep -E 'win-local|win-uniclipboard' || echo "no SMB mount yet"

If nothing is mounted, stop and ask the user before running mount_smbfs — it prompts for the Windows password interactively and the agent shouldn't silently do credential prompts. Hand the user the exact commands and let them run via ! <cmd>.

Default: broad mount of AppData/Local at /tmp/win-local

This is what dual-logs.sh expects out of the box. It exposes every Windows uniclipboard profile dir at once, so you can switch profiles without re-mounting:

mkdir -p /tmp/win-local
mount_smbfs '//DESKTOP-HIC7MLI/Users/mark/AppData/Local' /tmp/win-local

After mount you'll see dirs like /tmp/win-local/app.uniclipboard.desktop, /tmp/win-local/app.uniclipboard.desktop-dev, plus old version-suffixed ones. The script auto-detects the freshest one (see "Profile resolution" below).

Legacy: narrow mount at /tmp/win-uniclipboard

Older sessions sometimes still use this — mounting only one profile dir directly. The script supports it via the WIN_LOGS env override (full-path bypass of $WIN_BASE):

mkdir -p /tmp/win-uniclipboard
mount_smbfs '//DESKTOP-HIC7MLI/Users/mark/AppData/Local/app.uniclipboard.desktop-<WIN_PROFILE>' /tmp/win-uniclipboard

# Then for every invocation:
WIN_LOGS=/tmp/win-uniclipboard/logs .agents/skills/dual-side-debug/dual-logs.sh status

Prefer the broad mount unless there's a specific reason — it pins you to one profile and requires re-mounting to switch.

Tearing down

If the mount is wedged (Finder hangs, ls blocks for 30s), unmount cleanly before re-mounting:

umount /tmp/win-local   # or /tmp/win-uniclipboard

If umount fails because the path is busy, fall back to diskutil unmount force /tmp/win-local.

Profile resolution (DO NOT skip this step)

Mac and Windows each have their own active profile, and they are not always the same name. The script resolves each side independently.

Mac profile

Default is dev (package.json's wails:dev script sets UC_PROFILE=dev). Treat dev as the assumed Mac profile unless the user said otherwise. The user sometimes runs other profiles (a, b for wails:dev:profile a/b, or ad-hoc names like abc). Override with --profile <name>.

Windows profile

The script auto-detects the Windows profile by scanning $WIN_BASE for the profile dir whose latest log file has the newest mtime. This handles the common case where the Win side is on a different profile than the Mac side, without you having to know which one. Override with --win-profile <name> (or --win-profile default for the no-suffix app.uniclipboard.desktop dir).

Always run status first

Before answering any question that depends on log content, run:

.agents/skills/dual-side-debug/dual-logs.sh status

Then judge:

1. Does the assumed Mac profile's log directory exist?
2. For each side, is the latest log file's mtime close to "now" (live (<2m) or recent (<10m) is good; anything older means the process probably isn't running on that profile)?
3. On the Win side, the status output shows which profile was auto-detected and prints the alternatives sorted by mtime — sanity-check that it picked the one the user actually meant.

If the assumed profile dir is missing, OR the freshness is stale / old / cold while the user is actively reproducing, stop and ask the user to confirm. Suggest a likely candidate from the available-profiles list. Example:

dev profile dir doesn't exist on Mac. The most recently active Mac profile is abc (last write 30s ago). Should I use abc, or are you running with a different UC_PROFILE?

Do not silently fall back. Wrong profile = looking at frozen logs from a previous session.