diff --git a/docs/plans/2026-07-09-remote-sync-runtime-path-design.md b/docs/plans/2026-07-09-remote-sync-runtime-path-design.md new file mode 100644 index 00000000..7bb59a79 --- /dev/null +++ b/docs/plans/2026-07-09-remote-sync-runtime-path-design.md @@ -0,0 +1,33 @@ +# Remote Sync Runtime PATH Design + +## Problem + +`subminer sync ` can locate a remote launcher while still failing to run +it. The generated launcher uses `#!/usr/bin/env bun`, and non-interactive SSH +shells commonly omit Bun's install directory from `PATH`. + +## Design + +Remote launcher probes and invocations will use a deterministic `PATH` prefix +covering SubMiner and Bun's supported/common locations: + +- `$HOME/.local/bin` +- `$HOME/.bun/bin` +- `/opt/homebrew/bin` +- `/usr/local/bin` +- `/usr/bin` +- `/bin` + +Resolution will run ` --help` under that PATH instead of only using +`command -v`. This confirms both the launcher and its shebang runtime work +before sync creates or transfers snapshots. The same prefixed command returned +by resolution will be used for remote snapshot and merge operations. + +`--remote-cmd` remains a launcher path override and receives the same runtime +PATH. Remote commands continue to be shell-quoted where user-controlled. + +## Validation + +Add focused resolver coverage that simulates an SSH shell where only the +prefixed PATH can start SubMiner. Run launcher unit tests, type checking, docs +tests/build, and the SubMiner launcher/docs verification lanes.