8000 Warn when the resolved claude is a Windows binary under /mnt/ (#31) by simon-inkie · Pull Request #60 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .specs/31-warn-windows-claude/SPEC.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# 31 Warn when the resolved claude is a Windows binary under /mnt/

## TL;DR
On WSL, `claude` can resolve to a Windows executable. Add one shared check that warns, naming the path and the fix.

## Scope
- `packages/base/bin/claude-binary-check.sh`: `claude_binary_is_foreign`, `warn_if_foreign_claude`.
- Called once per run from `boot-agents.sh` and `workspace.sh` (before the launch loop) and `create-agent.sh` (before the verify probe).
- INSTALL.md note under Known limitations.

## Acceptance
- A path under `/mnt/` or ending `.exe`/`.cmd` prints a warning with the path, the problem and the fix.
- A normal path prints nothing.
- Launch is not blocked.

## Test plan
`packages/base/test/claude-binary-check.test.sh`, registered in `shell-suites.test.ts`: fake `/mnt/c` path, `.exe`/`.cmd`, normal paths, absent claude.

## Decisions log
- Warn only, not stop: a Windows claude can still run through WSL interop, and the path alone does not prove breakage. Stopping would lock out working setups.
- Case-insensitive on `.exe`/`.cmd` is limited to upper and lower forms; mixed case is not worth a `shopt`.

## Follow-ups
None.

## Review feedback
Opus round 1 (approve, no blockers):
1. Warning printed once per agent. Fixed: called once before the loop in boot-agents.sh and workspace.sh.
2. INSTALL.md note sat above the section's opening line. Fixed: moved alongside the other bold entries.
3. Check runs in the script's shell, not the tmux pane's. Documented as best-effort in the lib header.
Nits, not changed: symlinks are not resolved (noted in the lib header); any Linux path under /mnt/ warns (accepted); mixed-case .Exe missed (deliberate).
7 changes: 7 additions & 0 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -687,6 +687,13 @@ Current, verified, and written down rather than discovered later.
**No authentication.** Repeated here because it belongs on any list of this
kind. See the top of this document.

**On WSL, `claude` can resolve to a Windows binary.** PATH often includes
Windows directories, so `command -v claude` may return a path under `/mnt/c/`
or ending in `.exe` or `.cmd`. The boot, workspace and create-agent scripts
print a warning naming that path and carry on; they do not stop, because a
Windows binary can still work through WSL interop. If agents fail to start,
install the Linux build inside WSL or put its directory earlier in `PATH`.

**A complete, valid header quoted inside a message body splits that message
in two.** Fixed on 2026-08-14, and this is what is left of it. Both readers,
the python3 CLI and the web application, used to take a block boundary off
Expand Down
3 changes: 3 additions & 0 deletions packages/base/bin/boot-agents.sh
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,7 @@ fi

# Pinned claude session ids, shared with workspace.sh.
. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/claude-session.sh"
. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/claude-binary-check.sh"

# Per-agent runtime (claude default; override via $AGENTS_HOME/<name>/.runtime).
get_runtime() {
Expand Down Expand Up @@ -781,6 +782,8 @@ ALREADY_UP=0
WAITING=0
FAILED=0
ARMED=0
# Once for the whole boot, not per agent. Best-effort: see claude-binary-check.sh.
warn_if_foreign_claude
for a in "${AGENTS[@]}"; do
if outcome=$(launch_agent "$a"); then
readiness_check=wait_for_readiness
Expand Down
44 changes: 44 additions & 0 deletions packages/base/bin/claude-binary-check.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# claude-binary-check.sh - warn when `claude` resolves to a Windows binary.
# Sourced, not run. Defines functions only; sourcing has no side effects.
#
# On WSL, PATH usually includes Windows directories, so `command -v claude` can
# resolve to claude.exe or claude.cmd under /mnt/c/... instead of the Linux
# install. That binary starts in a Windows process with Windows paths, so the
# agent's home, CLAUDE.md imports and session files are not where it looks, and
# the failure shows up later as a pane that does nothing useful.
#
# WARN, DO NOT STOP. A Windows claude can still run through WSL interop, and
# the path alone does not prove it is broken. Refusing to launch would lock out
# a setup that works, so this prints a warning to stderr and returns 0 either
# way. The launchers carry on.
#
# BEST-EFFORT. The check resolves `claude` in the calling script's shell, but
# the launchers start it in a tmux pane shell via send-keys, whose PATH can
# differ (rc files, .env.secrets). The warning can therefore be wrong in either
# direction. Symlinks are not followed, so a link into /mnt/ stays silent.
# Launchers call it once per run, not per agent.

# claude_binary_is_foreign <path>: success if the path looks like a Windows
# binary reached from WSL (under /mnt/, or ending in .exe or .cmd).
claude_binary_is_foreign() {
case "${1:-}" in
/mnt/*|*.exe|*.EXE|*.cmd|*.CMD) return 0 ;;
*) return 1 ;;
esac
}

# warn_if_foreign_claude [path]: with no argument, resolves `claude` on PATH.
# Prints nothing when it is absent or looks like a normal Linux install.
warn_if_foreign_claude() {
local resolved="${1:-}"
[[ -n "$resolved" ]] || resolved="$(command -v claude 2>/dev/null)" || return 0
claude_binary_is_foreign "$resolved" || return 0
{
printf 'WARNING: `claude` resolves to %s\n' "$resolved"
printf ' That looks like a Windows binary reached through WSL. Agents may fail to\n'
printf ' start, or start against the wrong paths, with no clear error.\n'
printf ' Fix: install the Linux build inside WSL, or put its directory earlier in\n'
printf ' PATH than the Windows one (check with: command -v claude).\n'
} >&2
return 0
}
3 changes: 3 additions & 0 deletions packages/base/bin/create-agent.sh
Original file line number Diff line number Diff line change
Expand Up @@ -717,6 +717,9 @@ if ! command -v claude >/dev/null 2>&1; then
report_cannot_verify "No \`claude\` on PATH, so there was nothing to ask."
fi

. "$SCRIPT_DIR/claude-binary-check.sh"
warn_if_foreign_claude

PROBE_PROMPT="Answer from your own context, not by reading any files, and reply with exactly two lines and nothing else:
name: <your name>
boot phrase: <the boot phrase recorded in your identity file>
Expand Down
4 changes: 4 additions & 0 deletions packages/base/bin/workspace.sh
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ fi

# Pinned claude session ids, shared with boot-agents.sh.
. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/claude-session.sh"
. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/claude-binary-check.sh"

get_runtime() {
local agent="$1"
Expand Down Expand Up @@ -110,6 +111,9 @@ start_watcher() {
tmux split-window -d -t "$target" -h -p 15 "exec $WATCHER_SCRIPT $target" 2>/dev/null || true
}

# Once for the whole workspace, not per agent. Best-effort: see claude-binary-check.sh.
warn_if_foreign_claude

# Create the base session if it doesn't exist
if ! tmux has-session -t "$SESSION" 2>/dev/null; then
FIRST="${AGENTS[0]}"
Expand Down
37 changes: 37 additions & 0 deletions packages/base/test/claude-binary-check.test.sh
8 F133
Original file line numberDiff line number Diff line change
@@ -0,0 +1,37 @@
#!/usr/bin/env bash
# Tests for bin/claude-binary-check.sh.
#
# bash packages/base/test/claude-binary-check.test.sh
#
# Feeds the check fake paths. Nothing is executed or read from disk.
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
. "$HERE/../bin/claude-binary-check.sh"

PASS=0
FAILS=0
pass() { echo "PASS $1"; PASS=$((PASS+1)); }
fail() { echo "FAIL $1${2:+ -- $2}"; FAILS=$((FAILS+1)); }

# A Windows path warns, names the path, gives the fix, and does not fail.
out="$(warn_if_foreign_claude /mnt/c/tools/claude.exe 2>&1)"; rc=$?
[[ "$rc" == 0 ]] && pass "windows path: returns 0 (warn only)" || fail "windows path: returns 0" "rc=$rc"
[[ "$out" == *"/mnt/c/tools/claude.exe"* ]] && pass "windows path: warning names the path" || fail "windows path: names the path" "$out"
[[ "$out" == *"PATH"* && "$out" == *"Linux"* ]] && pass "windows path: warning says how to fix" || fail "windows path: says how to fix" "$out"

# Other Windows shapes.
for p in /mnt/d/tools/claude /opt/x/claude.cmd /usr/local/bin/claude.EXE; do
[[ -n "$(warn_if_foreign_claude "$p" 2>&1)" ]] && pass "warns for $p" || fail "warns for $p"
done

# Normal Linux paths stay silent.
for p in /usr/local/bin/claude /opt/demo/bin/claude /opt/mnt/bin/claude; do
[[ -z "$(warn_if_foreign_claude "$p" 2>&1)" ]] && pass "silent for $p" || fail "silent for $p"
done

# With no argument it resolves from PATH; a PATH without claude is silent.
[[ -z "$(PATH=/nonexistent warn_if_foreign_claude 2>&1)" ]] && pass "absent claude: silent" || fail "absent claude: silent"

echo "$PASS passed, $FAILS failed"
[[ "$FAILS" == 0 ]]
1 change: 1 addition & 0 deletions packages/base/test/shell-suites.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ const SUITES = [
"activity-sweep.test.sh",
"stuck-pane-sweep.test.sh",
"boot-agents.test.sh",
"claude-binary-check.test.sh",
] as const;

describe("ported shell suites", () => {
Expand Down
Loading
0