feat: add Windows-to-WSL launcher bridge

[sbracewell64]

Intent

Implement the Windows-to-WSL launcher bridge for Firstmate by adding the repository-root firstmate.bat and bin/fm-wsl-entry.sh, so a Windows double-click reaches the existing bin/fm-launch.sh harness menu and Herdr launch/attach flow. The bridge must handle Windows repository paths containing spaces, enter WSL deterministically without relying on a login shell or caller working directory, propagate launcher arguments and exit status, and print actionable failures that remain visible after a double-click. Add executable regression coverage for the WSL entry and native batch command construction without requiring a live Windows/WSL session, plus current operator and contributor documentation. This is a new upstream contribution based only on origin/main; the pending launcher PR is a dependency and none of its commits may be copied into this branch. Keep the diff limited to the bridge, its tests/CI coverage, and documentation required to register and operate it. Do not place a launcher in E:/Agentic Engineering or retire any platform launcher in this change.

What Changed

• Add a repository-root Windows batch launcher and deterministic WSL entrypoint that support spaced paths, forward arguments and exit codes, and keep actionable failures visible.
• Add regression coverage and a Windows CI lane for batch command construction, WSL entry behavior, and platform-specific line endings.
• Document Windows/WSL prerequisites, launch behavior, troubleshooting, and contributor ownership.

Risk Assessment

✅ Low: The bridge is well-bounded, satisfies the source-verifiable intent, preserves the pending launcher as an uncopied dependency, and includes appropriate portable and native Windows regression coverage.

Testing

Inspected the base-to-target scope and ancestry, ran the focused bridge suite twice—including its native Windows cmd.exe path—manually captured both sides of the bridge with nonzero status propagation and reviewer-visible CLI transcripts, verified CRLF/LF checkout behavior, and confirmed testing left the worktree clean; all targeted checks passed. No screenshot was captured because the changed end-user surface is a terminal launcher, for which exact native command transcripts are the direct rendered evidence.

Evidence: Native Windows batch command construction

arg1=[--cd] arg2=[\wsl.localhost\Ubuntu\tmp\no-mistakes-evidence\01KYWDZ0HAM6ZWX4JPBAGY4WE4\fm-wsl-entry.1Z36Z0\batch case\Firstmate root with spaces.] arg3=[--exec] arg4=[/bin/bash] arg5=[./bin/fm-wsl-entry.sh] arg6=[--print-menu] arg7=[two words]

arg1=[--cd]
arg2=[\\wsl.localhost\Ubuntu\tmp\no-mistakes-evidence\01KYWDZ0HAM6ZWX4JPBAGY4WE4\fm-wsl-entry.1Z36Z0\batch case\Firstmate root with spaces\.]
arg3=[--exec]
arg4=[/bin/bash]
arg5=[./bin/fm-wsl-entry.sh]
arg6=[--print-menu]
arg7=[two words]

Evidence: Double-click-visible actionable failure

Firstmate could not start through WSL. Exit status: 37 Review the error above. If WSL itself did not start, run "wsl --install" and retry.

'\\wsl.localhost\Ubuntu\home\shane\.no-mistakes\worktrees\5f306883d81c\01KYWDZ0HAM6ZWX4JPBAGY4WE4'
CMD.EXE was started with the above path as the current directory.
UNC paths are not supported.  Defaulting to Windows directory.

Firstmate could not start through WSL. Exit status: 37
Review the error above. If WSL itself did not start, run "wsl --install" and retry.

Evidence: WSL entry-to-launcher behavior

cwd=[/tmp/no-mistakes-evidence/01KYWDZ0HAM6ZWX4JPBAGY4WE4/fm-wsl-entry.1Z36Z0/Firstmate repo with spaces] arg1=[--print-menu] arg2=[value with spaces] arg3=[]

cwd=[/tmp/no-mistakes-evidence/01KYWDZ0HAM6ZWX4JPBAGY4WE4/fm-wsl-entry.1Z36Z0/Firstmate repo with spaces]
arg1=[--print-menu]
arg2=[value with spaces]
arg3=[]

Evidence: Focused bridge test log

All focused launcher checks passed, including native cmd.exe execution.

ok - fm-wsl-entry: repository paths with spaces, arguments, and exit status pass through unchanged
ok - fm-wsl-entry: a missing fleet launcher refuses with an actionable repair
ok - firstmate.bat: one explicit WSL command preserves a spaced root, arguments, and exit status
ok - bridge line endings: checkouts deliver a CRLF batch launcher and an LF WSL entry

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• git diff --check f7d0d0a703a717880656709d7906615505b3f2c0..717739bbca8b9b800acf53491d23fcbd8bef453e
• bash tests/fm-wsl-entry.test.sh
• TMPDIR=/tmp/no-mistakes-evidence/01KYWDZ0HAM6ZWX4JPBAGY4WE4 bash tests/fm-wsl-entry.test.sh
• Native cmd.exe /d /c run-test.cmd execution using the suite’s fake WSL seam; verified spaced --cd, direct /bin/bash, entry script, forwarded arguments, visible repair text, and exit status 37
• Direct bin/fm-wsl-entry.sh --print-menu "value with spaces" "" fixture execution from /; verified repository resolution and exit status 23
• file firstmate.bat bin/fm-wsl-entry.sh and git check-attr eol -- firstmate.bat bin/fm-wsl-entry.sh
• Ancestry/scope checks with git merge-base --is-ancestor, git diff --name-only, and git diff --quiet ... -- bin/fm-launch.sh
• git status --short after testing

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[sbracewell64]

Automated probe posted by the repository owner's Firstmate fleet (scout task afk-github-loop-architecture), not a human review request. Purpose: measure whether an automated independent code review can be requested and consumed on a pull request without a person in the loop. Review only — please do not push commits and do not open a pull request.

@codex review

Scope for this review: bin/fm-wsl-entry.sh, firstmate.bat, and tests/fm-wsl-entry.test.sh. Please report correctness, portability, quoting/escaping, and error-path defects with explicit file and line references, and state plainly if you find none.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 027366a81f

ℹ️ 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]

Include the launcher that this entrypoint always executes

Captain, every fresh checkout of this commit fails here because bin/fm-launch.sh is absent from the commit (a repository-wide tree search finds no such file), so the preceding readability check always exits with status 1 and firstmate.bat can never launch Firstmate. The tests conceal this by manufacturing a fake fm-launch.sh in their fixture; add the real launcher dependency or target an existing tracked entrypoint.

Useful? React with 👍 / 👎.