feat: add Windows platform detection seam

[ViktorTsvetkov]

Intent

Add bin/fm-platform-lib.sh: a self-contained platform-detection seam (fm_platform_is_windows, uname, HOME/USERPROFILE and TMPDIR fallbacks, MSYS ps parsing) that later Windows work sits behind. Inert on POSIX.

What Changed

• Add a shared platform seam for Windows, macOS, and POSIX detection with HOME and temporary-directory fallbacks.
• Support native and MSYS/Cygwin process-table parsing with locale-stable PID identity checks.
• Document the helper and add focused coverage for Windows path fallbacks, POSIX behavior, and process parsing.

Risk Assessment

✅ Low: The new platform seam is self-contained and inert until sourced, with conservative Windows fallbacks and no material correctness risks found in the reviewed changes.

Testing

The successful baseline full shell suite was supplemented by a focused platform-library rerun and an end-to-end native POSIX/simulated MSYS transcript; all expected platform detection, fallback, and process-parsing behavior worked, and the worktree remained clean.

Evidence: POSIX and simulated MSYS platform-seam transcript

POSIX uname: Linux
POSIX is_windows: no
POSIX home: /home/viktor
POSIX temp with TMPDIR override: /tmp
POSIX current-shell ppid: 674011
MSYS uname (from uname command): MSYS_NT-10.0
MSYS is_windows: yes
MSYS home fallback: /c/Users/Captain
MSYS configured temp: C:\Temp
MSYS default temp: /tmp
MSYS fixed-ps ppid: 1234
MSYS fixed-ps command: /usr/bin/bash --login
MSYS fixed-ps stime: Jan 29

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.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• Baseline previously completed: command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• Focused test: bash tests/fm-platform-lib.test.sh
• Manual evidence check: sourced bin/fm-platform-lib.sh in native Linux and simulated MSYS shells with fake uname and fixed-column ps, recording detection, HOME/TMPDIR resolution, and process fields in platform-seam-transcript.txt
• Cleanup verification: git status --short

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

Automated reminder: thanks for the PR! This branch currently has a merge conflict with the base branch.

When you get a chance, please rebase onto (or merge) the latest base branch, resolve the conflict, and push. After that, checks will re-run and the PR will get looked at again.

_{Noted for firstmate#506 at aa3bfcc3.}

[ViktorTsvetkov]

Rebased onto latest main — the docs/scripts.md conflict is resolved (upstream's reworded fm-config-inherit-lib.sh row kept verbatim; this branch still adds exactly one row).

While re-running it through the gate, the review surfaced three real defects in this helper. All are fixed:

• Cygwin ps can prefix a row with a status column (I/S/O), so treating the first token as the PID made the fallback reject ordinary interactive or stopped processes.
• Older start times render as two tokens (Jan 29), which shifted every column after STIME — comm came back as 29.
• The fallback PID identity was only time-of-day plus command, with no date, so a PID reused on a later day by the same executable could match stale ownership metadata; it also read ps twice, which can straddle a reuse. That fallback is removed and the identity now fails closed rather than returning a possibly-wrong answer.

The shape of the change is unchanged: bin/fm-platform-lib.sh and tests/fm-platform-lib.test.sh (both new) plus one row in docs/scripts.md. Nothing else is touched, and the helper has no runtime callers yet. Checks are green.

[notno]

We have been running an independent native-Windows port of firstmate (Git Bash / MSYS2, no WSL) on a fork, driving the Herdr backend on Windows 11. We arrived at the same seam independently: our fork has a bin/fm-platform-lib.sh with fm_platform_uname and an MSYS/MinGW predicate, plus two helpers this PR does not have — a filesystem mode-bit capability probe and a file-mode reader, both needed because MSYS cannot always express POSIX permission bits.

The two files look complementary rather than competing. This PR covers process-table fields, home and temp resolution, and PID identity; ours covers permission-bit capability. One notable difference: this PR's predicate matches CYGWIN* as well as MINGW*/MSYS*, which is the broader and probably more correct form.

@ViktorTsvetkov — this has been open since July and issue #504 asks contributors to help it rather than open a competing PR. Are you still working on it? If not, we are willing to carry it forward through the no-mistakes pipeline, keeping your commits and authorship intact. We can also supply real Windows 11 / Git Bash evidence, which is the part that is hard to produce without the hardware.

Either way we will not open a competing PR.

[kunchenguid]

Speaking as Kun's firstmate:

Scheduled 11:10am PT 8/24 pass. VISION.md read in full from current main 038d0f7ec6ba7238a151722931434dcf06ff37c4 (#2942). FIRST LOOK / ancient (opened 2026-07-12). Inspected whether the seam already landed. Never messaged the captain.

Current main does not contain bin/fm-platform-lib.sh. Windows work on main today is a workflow_dispatch spike (.github/workflows/windows-herdr-spike.yml) plus ad-hoc Windows/MSYS notes in watcher/wake helpers — not this shared seam. Open related PRs (#2918 drive-letter herdr sockets, #2769 / #2621 Windows session-lock) do not add fm-platform-lib.sh. Not a leftover to close. notno's 8/24 comment (independent native-Windows fork arriving at the same seam) is extra evidence it is still wanted, not that it already shipped.

VISION (inspected the new bin/fm-platform-lib.sh + tests; no production caller in this PR). Per-rule: scripts-own-mechanics aligns (inert sourced helper). Authority-is-explicit / new-capability-as-option does not align as a land: this is product platform expansion, even though POSIX behavior stays inert until sourced. Fleet-outlives-vendor cannot tell (no Windows caller wired). Scope aligns only as a leaf helper.

Class: default-behavior. Windows platform support is product expansion. Do not auto-merge.

Security: none. Detection/HOME/TMPDIR/ps helpers only; no workflow-file change; no network; test seams FM_PLATFORM_UNAME / FM_PLATFORM_IS_WINDOWS.

Overlap: docs/scripts.md only vs standing holds. No herdr.sh / spawn / teardown / lock-lib edit.

CI / NM: HEAD 4de14560f0a8b765445b1b88d419b17fb8f544af. mergeable MERGEABLE, mergeStateStatus UNSTABLE. ahead 4 / behind 232 vs current main. No no-mistakes-pipeline-attestation:v1 in the body. CI on this HEAD is from 2026-07-21: Require no-mistakes SUCCESS (29851096098); CI cancelled (29851096050). Stale vs current main. Not first-time-fork pending (workflows already ran in July). No approval this pass.

Land-eligible rec: NO (default-behavior platform expansion; 232 behind; no matching NM attestation; stale CI). Captain-flag NOW: no. Will not close.

Captain-decision to take Windows platform expansion. Waiting-on-author if they still want it: rebase onto current main and restamp no-mistakes. Not auto-merge.

[kunchenguid]

Speaking as Kun's firstmate: first look on current main 038d0f7ec6ba.

class=opt-in / inert seam. bin/fm-platform-lib.sh is POSIX-inert detection. Not a Windows port landing. Not auto while 232 behind and NM is missing.

VISION.md: scripts align (detection is exact). Authority aligns if later Windows work stays opt-in. Spine mixed (new primitive; later work can compose). Vendor aligns. Scope mixed (platform expansion is product). Restart n/a.

This HEAD: 4de14560f0a8b765445b1b88d419b17fb8f544af. MERGEABLE / UNSTABLE, ahead 4 / behind 232, diverged. No no-mistakes-pipeline-attestation:v1. CI run 29851096050 cancelled (stale). First-time author (0 merged PRs).

Waiting on author: rebase onto current main, attach a matching attestation, re-run CI. Not a captain-decision hold.

[notno]

Two triage comments landed 68 seconds apart with opposite conclusions. The first classes this default-behavior, says "Captain-decision to take Windows platform expansion", and recommends against landing. The second classes it opt-in, calls it an inert seam, and says explicitly "Not a captain-decision hold. Waiting on author."

Which of the two stands? It decides whether rebasing and restamping this PR is worth an author's effort now, or whether it needs a product call first. Both agree on the mechanics — 232 behind, no matching attestation, CI stale since 21 July — so the mechanical work is clear either way; what is not clear is whether doing it changes anything.

Separately, on carrying this forward: we can prepare the rebase onto current main and run it through the no-mistakes pipeline, but this is @ViktorTsvetkov's branch and we cannot push to it. If they stay unavailable, is there a preferred path — a fresh PR carrying their commits and authorship intact, or something else? We would rather ask than guess, and we will not open a competing PR without an answer here.