[gmickel]

Why

Anyone who wants flow-next to run on a different flowctl (their own build, a port, a fork under test) had to edit the FLOWCTL= line in every skill. That breaks make-pr and map, which look for helper scripts beside $FLOWCTL. This PR puts the hand-off in the two bundled launchers instead. Every skill, agent and host already calls one of them.

What changes for a user or operator

• Set FLOW_NEXT_FLOWCTL=/path/to/flowctl and every call goes there with its arguments, before the launcher looks for Python. The launcher returns that flowctl's exit code.
• A value the system cannot run stops with a clear error and never falls back to the bundled flowctl, so two flowctls can't write one .flow/.
• A value that names the launcher itself runs the launcher as usual.
• With the variable unset nothing changes. Over 80 alternating list --json calls, main took 315.9 ms per call and this branch 315.6 ms.

I named it FLOW_NEXT_FLOWCTL because an unrelated CLI also called flowctl (withObsrvr's) tells its users to set FLOWCTL_BIN.

Scope

• plugins/flow-next/scripts/flowctl: exec under shopt -s execfail, so the OS decides what runs. Git Bash finds flowctl.exe from a bare flowctl path. A self check (-ef) covers both a direct path and a symlink.
• plugins/flow-next/scripts/flowctl.cmd: normalizes the value with %%~fI, skips itself and its bash twin, checks the exact file or a PATHEXT variant, then runs CALL. A failed CALL sets errorlevel 1, which a real flowctl can also return, so the error message needs this pre-check.
• plugins/flow-next/tests/test_startup_bootstrap.py: 5 tests:
  • hand-off with no Python on PATH;
  • loud failure for a missing file, a directory and a non-executable file;
  • self path, direct and through a symlink;
  • empty value;
  • FLOWCTL_BIN ignored.
• .github/workflows/test-flow-next.yml: two steps on windows-latest.
  • PowerShell to flowctl.cmd and Git Bash to flowctl. Each covers a hand-off returning exit 7, an extensionless path, a missing path or directory failing loudly with no .flow/ created, FLOWCTL_BIN ignored, and a self path.
  • The PowerShell step also checks a forward-slash self path.
  • The Git Bash step also checks a backslash path.
• plugins/flow-next/docs/flowctl.md and its Codex mirror: one paragraph.
• 9.1.0 version bump and changelog.

Verification

• Full suite locally: 4070 tests, 0 failures.
• sync-codex.sh --check reports the Codex mirror is fresh.
• Spike CI run 39177634927: all 12 jobs green, Windows included.
• End to end against a TypeScript flowctl, using the skill-shaped Claude Code and Codex FLOWCTL chains: init, spec create and list went to it with the variable set and to Python without it. make-pr's and map's helper scripts still resolve beside the launcher.

https://claude.ai/code/session_01LbHwMnkD6ovBw6n8cnD8hQ